diff --git a/README.md b/README.md index 5b81e41cd..345657728 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ # n8n Docs -This repository hosts the documentation for [n8n](https://n8n.io/), an extendable workflow automation tool which enables you to connect anything to everything via its open, [fair-code](https://faircode.io/) model. The documentation is live at [docs.n8n.io](https://docs.n8n.io/). +This repository hosts the documentation for [n8n](https://n8n.io/), an extendable workflow automation tool which enables you to connect anything to everything. The documentation is live at [docs.n8n.io](https://docs.n8n.io/). ## Previewing and building the documentation locally diff --git a/_snippets/code-examples/methods-list.md b/_snippets/code-examples/methods-list.md deleted file mode 100644 index b2eab5c6e..000000000 --- a/_snippets/code-examples/methods-list.md +++ /dev/null @@ -1,7 +0,0 @@ -n8n provides the following methods: - -- `$evaluateExpression`: evaluates a string as an expression. -- `$items`: returns items from a given node -- `$item`: returns an item at a given index -- `$jmespath()`: perform a search on a JSON object using JMESPath. -- `$node`: data from a specified node diff --git a/_snippets/code-examples/variables-list.md b/_snippets/code-examples/variables-list.md deleted file mode 100644 index 92323438e..000000000 --- a/_snippets/code-examples/variables-list.md +++ /dev/null @@ -1,13 +0,0 @@ -n8n provides the following variables: - -- `$binary`: incoming binary data from a node -- `$data`: incoming raw data from a node -- `$env`: contains environment variables -- `$json`: incoming JSON data from a node -- `$now`: a Luxon object containing the current timestamp. Equivalent to `DateTime.now()`. -- `$parameters`: parameters of the current node -- `$position`: the index of an item in a list of items -- `$resumeWebhookUrl`: the webhook URL to call to resume a waiting workflow. -- `$runIndex`: how many times the node has been executed. Zero-based (the first run is 0, the second is 1, and so on). -- `$today`: a Luxon object containing the current timestamp, rounded down to the day. Equivalent to `DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 })`. -- `$workflow`: workflow metadata diff --git a/_snippets/data/data-mapping/item-linking-code-node.md b/_snippets/data/data-mapping/item-linking-code-node.md new file mode 100644 index 000000000..b6e480d92 --- /dev/null +++ b/_snippets/data/data-mapping/item-linking-code-node.md @@ -0,0 +1,95 @@ +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](/data/data-mapping/data-item-linking/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 `$("").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](/data/data-mapping/data-item-linking/item-linking-concepts/) handles the other scenarios. + +To control item linking, set `pairedItem` when returning data. For example, to link to the item at index 0: + +```js +[ + { + "json": { + . . . + }, + "pairedItem": 0 + } +] +``` + + +### pairedItem usage example + +Take this input data: + +```json +[ + { + "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: + +```js +newItems = []; +for(let i=0; i **Clash Handling**. +2. Choose which input to prioritize, or choose **Always Add Input Number to Field Names** to keep all fields and values, with the input number appended to the field name to show which input it came from. diff --git a/_snippets/integrations/builtin/core-nodes/if-merge-branch-execution.md b/_snippets/integrations/builtin/core-nodes/merge/if-merge-branch-execution.md similarity index 80% rename from _snippets/integrations/builtin/core-nodes/if-merge-branch-execution.md rename to _snippets/integrations/builtin/core-nodes/merge/if-merge-branch-execution.md index 4889ec32c..faf821c77 100644 --- a/_snippets/integrations/builtin/core-nodes/if-merge-branch-execution.md +++ b/_snippets/integrations/builtin/core-nodes/merge/if-merge-branch-execution.md @@ -1,7 +1,7 @@ -### Branch execution with If and Merge nodes - If you add a Merge node to a workflow containing an If node, it can result in both output branches of the If node executing. +The Merge node is triggered by one branch, then goes and executes the other branch. + For example, in the screenshot below there's a workflow containing a Set node, If node, and Merge node. The standard If node behavior is to execute one branch (in the screenshot, this is the **true** output). However, due to the Merge node, both branches execute, despite the If node not sending any data down the **false** branch. -![Screenshot of a simple workflow. The workflow has a Set node, followed by an If node. It ends with a Merge node.](/_images/integrations/builtin/core-nodes/merge/if-merge-node.png) \ No newline at end of file +![Screenshot of a simple workflow. The workflow has a Set node, followed by an If node. It ends with a Merge node.](/_images/integrations/builtin/core-nodes/merge/if-merge-node.png) diff --git a/_snippets/integrations/builtin/credentials/google/enable-apis.md b/_snippets/integrations/builtin/credentials/google/enable-apis.md new file mode 100644 index 000000000..442e6144c --- /dev/null +++ b/_snippets/integrations/builtin/credentials/google/enable-apis.md @@ -0,0 +1,4 @@ +1. Access your [Google Cloud Console - Library](https://console.cloud.google.com/apis/library){:target=_blank .external-link}. Make sure you're in the correct project. +1. Search for and select the API(s) you want to enable. For example, for the Gmail node, search for and enable the Gmail API. + +1. Select **ENABLE**. diff --git a/docs/integrations/creating-nodes/archive/create-n8n-nodes-module.md b/archive/create-n8n-nodes-module.md similarity index 100% rename from docs/integrations/creating-nodes/archive/create-n8n-nodes-module.md rename to archive/create-n8n-nodes-module.md diff --git a/archive/item.md b/archive/item.md new file mode 100644 index 000000000..976273040 --- /dev/null +++ b/archive/item.md @@ -0,0 +1,33 @@ +# `$item(index: number, runIndex?: number)` + +With `$item` you can access the data of parent nodes. That can be the item data but also +the parameters. It expects as input an index of the item the data should be returned for. This is +needed because for each item the data returned can be different. This is probably straightforward for the +item data itself but maybe less for data like parameters. The reason why it is also needed, is +that they may contain an expression. Expressions get always executed of the context for an item. +If that would not be the case, for example, the Email Send node not would be able to send multiple +emails at once to different people. Instead, the same person would receive multiple emails. + +The index is 0 based. So `$item(0)` will return the first item, `$item(1)` the second one, and so on. + +By default the item of the last run of the node will be returned. So if the referenced node ran +3x (its last runIndex is 2) and the current node runs the first time (its runIndex is 0) the +data of runIndex 2 of the referenced node will be returned. + +For more information about what data can be accessed via `$node`, check out the `Variable: $node` [section](/code-examples/methods-variables/node/). + +Example: + +```typescript +// Returns the value of the JSON data property "myNumber" of Node "Set" (first item) +const myNumber = $item(0).$node["Set"].json["myNumber"]; +// Like above but data of the 6th item +const myNumber = $item(5).$node["Set"].json["myNumber"]; + +// Returns the value of the parameter "channel" of Node "Slack". +// If it contains an expression the value will be resolved with the +// data of the first item. +const channel = $item(0).$node["Slack"].parameter["channel"]; +// Like above but resolved with the value of the 10th item. +const channel = $item(9).$node["Slack"].parameter["channel"]; +``` diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.cron.md b/archive/n8n-nodes-base.cron.md similarity index 100% rename from docs/integrations/builtin/core-nodes/n8n-nodes-base.cron.md rename to archive/n8n-nodes-base.cron.md diff --git a/archive/n8n-nodes-base.function.md b/archive/n8n-nodes-base.function.md new file mode 100644 index 000000000..49f6d6740 --- /dev/null +++ b/archive/n8n-nodes-base.function.md @@ -0,0 +1,60 @@ +# Function + +!!! warning "Deprecated in 0.198.0" + n8n deprecated this node in version 0.198.0. Older workflows continue to work, and the node is still available in older versions n8n. From 0.198.0, n8n replaces the Function node with the [Code](/integrations/builtin/core-nodes/n8n-nodes-base.code/) node. + +Using the function node, you can: + +* Transform data from other nodes +* Implement custom functionality + +!!! note "Function node and function item node" + Note that the Function node is different from the [Function Item](/integrations/builtin/core-nodes/n8n-nodes-base.functionItem/) node. Refer to [Data | Code](/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](/data/data-structure/): understand the data you receive in the Function node, and requirements for outputting data from the node. +* [Item linking](/data/data-mapping/data-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](/code-examples/methods-variables-reference/) for more information. + + +## Output items + +When using the Function node, you must return data in the format described in [data structure](/data/data-structure/). + +This example creates 10 items with the IDs 0 to 9: + +```typescript +const newItems = []; + +for (let i=0;i<10;i++) { + newItems.push({ + json: { + id: i + } + }); +} + +return newItems; +``` + +## Manage item linking + +--8<-- "_snippets/data/data-mapping/item-linking-code-node.md" + +## 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](/hosting/configuration/#use-built-in-and-external-modules-in-function-nodes) guide. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.functionItem.md b/archive/n8n-nodes-base.functionItem.md similarity index 91% rename from docs/integrations/builtin/core-nodes/n8n-nodes-base.functionItem.md rename to archive/n8n-nodes-base.functionItem.md index 8348b9fb4..56c77b03e 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.functionItem.md +++ b/archive/n8n-nodes-base.functionItem.md @@ -1,5 +1,8 @@ # Function Item +!!! warning "Deprecated in 0.198.0" + n8n deprecated this node in version 0.198.0. Older workflows continue to work, and the node is still available in older versions n8n. From 0.198.0, n8n replaces the Function node with the [Code](/integrations/builtin/core-nodes/n8n-nodes-base.code/) node. + The Function Item node is used to add custom snippets to JavaScript code that should be executed once for every item that it receives as the input. !!! note "Keep in mind" diff --git a/archive/n8n-nodes-base.venafitlsprotectdatacentertrigger.md b/archive/n8n-nodes-base.venafitlsprotectdatacentertrigger.md new file mode 100644 index 000000000..3b0b9eb9d --- /dev/null +++ b/archive/n8n-nodes-base.venafitlsprotectdatacentertrigger.md @@ -0,0 +1,6 @@ +# Venafi TLS Protect Datacenter Trigger + +[Venafi](https://www.venafi.com/){:target=_blank .external-link} is a cybersecurity company providing services for machine identity management. They offer solutions to manage and protect identities for a wide range of machine types, delivering global visibility, lifecycle automation, and actionable intelligence. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/venafiTlsProtectDatacenter/). diff --git a/docs/integrations/creating-nodes/archive/node-developer-cli.md b/archive/node-developer-cli.md similarity index 100% rename from docs/integrations/creating-nodes/archive/node-developer-cli.md rename to archive/node-developer-cli.md diff --git a/docs/integrations/creating-nodes/archive/review-checklist.md b/archive/review-checklist.md similarity index 100% rename from docs/integrations/creating-nodes/archive/review-checklist.md rename to archive/review-checklist.md diff --git a/docs/_downloads/venafi-tpp.pdf b/docs/_downloads/venafi-tpp.pdf new file mode 100644 index 000000000..29d047674 Binary files /dev/null and b/docs/_downloads/venafi-tpp.pdf differ diff --git a/docs/_extra/css/extra.css b/docs/_extra/css/extra.css index 10ce2bef6..6b30a7bda 100644 --- a/docs/_extra/css/extra.css +++ b/docs/_extra/css/extra.css @@ -27,9 +27,30 @@ /* https://squidfunk.github.io/mkdocs-material/setup/changing-the-fonts/?h=font#additional-fonts */ --md-text-font: "Moderat-Regular-Web"; + /* https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions */ + --md-admonition-icon--details: url('data:image/svg+xml;charset=utf-8,'); } + + /* https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions */ + .md-typeset .admonition.details, + .md-typeset details.details { + border-color: var(--color-background-dark); + } + .md-typeset .details > .admonition-title, + .md-typeset .details > summary { + background-color: rgba(16,19,48, 0.1); + } + .md-typeset .details > .admonition-title::before, + .md-typeset .details> summary::before { + background-color: rgb(16,19,48); + -webkit-mask-image: var(--md-admonition-icon--details); + mask-image: var(--md-admonition-icon--details); + } + + + /* light mode */ @@ -131,12 +152,25 @@ white-space: pre; } -/* border on TOC */ -/* [data-md-color-scheme="light"] .md-nav--secondary { - border-left: 1px solid var(--color-primary); -} */ +/* bigger font in table */ +.table-without-whitespace-pre td:first-of-type { + white-space: unset; +} +.md-typeset table:not([class]) { + font-size: 0.75rem +} +/* img borders */ + +.md-typeset img, .md-typeset svg, .md-typeset video { + border: 1px solid #DBDFE7; + border-radius: 4px; +} + +.md-typeset :is(.emojione,.twemoji,.gemoji) svg { + border: none; +} /* dark mode */ /* [data-md-color-scheme="dark"] .md-header{ @@ -181,6 +215,12 @@ border-left: 1px solid var(--color-primary); } */ +code { + tab-size: 2; +} + +/* n8n classes */ + .inline-image { display:inline-block; max-width: 25px; @@ -188,8 +228,8 @@ vertical-align: middle; } -code { - tab-size: 2; +.inline-image > img { + border: none; } @@ -197,3 +237,5 @@ code { + + diff --git a/docs/_images/courses/level-one/chapter-one/Hacker-news-params.png b/docs/_images/courses/level-one/chapter-one/Hacker-news-params.png index b0ae87a4e..dcdcbbc9e 100644 Binary files a/docs/_images/courses/level-one/chapter-one/Hacker-news-params.png and b/docs/_images/courses/level-one/chapter-one/Hacker-news-params.png differ diff --git a/docs/_images/courses/level-one/chapter-one/Left-side-menu.png b/docs/_images/courses/level-one/chapter-one/Left-side-menu.png index fe5eee90f..8ad89db15 100644 Binary files a/docs/_images/courses/level-one/chapter-one/Left-side-menu.png and b/docs/_images/courses/level-one/chapter-one/Left-side-menu.png differ diff --git a/docs/_images/data/data-mapping/data-item-linking/item-linking.png b/docs/_images/data/data-mapping/data-item-linking/item-linking.png new file mode 100644 index 000000000..fa271263b Binary files /dev/null and b/docs/_images/data/data-mapping/data-item-linking/item-linking.png differ diff --git a/docs/_images/embed/white-label/about-modal.png b/docs/_images/embed/white-label/about-modal.png new file mode 100644 index 000000000..4e6ae0166 Binary files /dev/null and b/docs/_images/embed/white-label/about-modal.png differ diff --git a/docs/_images/embed/white-label/color-transition.gif b/docs/_images/embed/white-label/color-transition.gif new file mode 100644 index 000000000..0367f1d79 Binary files /dev/null and b/docs/_images/embed/white-label/color-transition.gif differ diff --git a/docs/_images/embed/white-label/logo-main-sidebar.png b/docs/_images/embed/white-label/logo-main-sidebar.png new file mode 100644 index 000000000..7552083ad Binary files /dev/null and b/docs/_images/embed/white-label/logo-main-sidebar.png differ diff --git a/docs/_images/embed/white-label/window-title.png b/docs/_images/embed/white-label/window-title.png new file mode 100644 index 000000000..7db3b1cb1 Binary files /dev/null and b/docs/_images/embed/white-label/window-title.png differ diff --git a/docs/_images/integrations/builtin/app-nodes/gmail/gmail1_node.png b/docs/_images/integrations/builtin/app-nodes/gmail/gmail1_node.png deleted file mode 100644 index b420e9691..000000000 Binary files a/docs/_images/integrations/builtin/app-nodes/gmail/gmail1_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/app-nodes/gmail/gmail2_node.png b/docs/_images/integrations/builtin/app-nodes/gmail/gmail2_node.png deleted file mode 100644 index 5973aecc5..000000000 Binary files a/docs/_images/integrations/builtin/app-nodes/gmail/gmail2_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/app-nodes/gmail/gmail_node.png b/docs/_images/integrations/builtin/app-nodes/gmail/gmail_node.png deleted file mode 100644 index 222f08785..000000000 Binary files a/docs/_images/integrations/builtin/app-nodes/gmail/gmail_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/app-nodes/gmail/workflow.png b/docs/_images/integrations/builtin/app-nodes/gmail/workflow.png deleted file mode 100644 index 0773bbd1b..000000000 Binary files a/docs/_images/integrations/builtin/app-nodes/gmail/workflow.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest1_node.png b/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest1_node.png deleted file mode 100644 index f66f1b900..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest1_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest2_node.png b/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest2_node.png deleted file mode 100644 index 46860330b..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest2_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest_node.png b/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest_node.png deleted file mode 100644 index 182aa1343..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/httprequest/httprequest_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/httprequest/workflow.png b/docs/_images/integrations/builtin/core-nodes/httprequest/workflow.png deleted file mode 100644 index ebd6b4217..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/httprequest/workflow.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/append-diagram.png b/docs/_images/integrations/builtin/core-nodes/merge/append-diagram.png new file mode 100644 index 000000000..6a2728e1d Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/append-diagram.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/append-mode.png b/docs/_images/integrations/builtin/core-nodes/merge/append-mode.png new file mode 100644 index 000000000..f08c2e689 Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/append-mode.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/function1_node.png b/docs/_images/integrations/builtin/core-nodes/merge/function1_node.png deleted file mode 100644 index ff740a69a..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/merge/function1_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/function_node.png b/docs/_images/integrations/builtin/core-nodes/merge/function_node.png deleted file mode 100644 index 4b6da4fb4..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/merge/function_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/merge-by-field-diagram.png b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-field-diagram.png new file mode 100644 index 000000000..17617b4b3 Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-field-diagram.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/merge-by-fields-mode.png b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-fields-mode.png new file mode 100644 index 000000000..9c743623d Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-fields-mode.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-diagram.png b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-diagram.png new file mode 100644 index 000000000..d3c7220fa Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-diagram.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-include-unpaired.png b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-include-unpaired.png new file mode 100644 index 000000000..1180feb19 Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-include-unpaired.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-mode-default.png b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-mode-default.png new file mode 100644 index 000000000..cb105ecf5 Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/merge-by-position-mode-default.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/merge_node.png b/docs/_images/integrations/builtin/core-nodes/merge/merge_node.png deleted file mode 100644 index a5222d914..000000000 Binary files a/docs/_images/integrations/builtin/core-nodes/merge/merge_node.png and /dev/null differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/multiplex-diagram.png b/docs/_images/integrations/builtin/core-nodes/merge/multiplex-diagram.png new file mode 100644 index 000000000..2eabcac4f Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/multiplex-diagram.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/multiplex-mode.png b/docs/_images/integrations/builtin/core-nodes/merge/multiplex-mode.png new file mode 100644 index 000000000..7f3d38031 Binary files /dev/null and b/docs/_images/integrations/builtin/core-nodes/merge/multiplex-mode.png differ diff --git a/docs/_images/integrations/builtin/core-nodes/merge/workflow.png b/docs/_images/integrations/builtin/core-nodes/merge/workflow.png index fe6a88c4e..cb22ab02c 100644 Binary files a/docs/_images/integrations/builtin/core-nodes/merge/workflow.png and b/docs/_images/integrations/builtin/core-nodes/merge/workflow.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/add-uri.png b/docs/_images/integrations/builtin/credentials/google/add-uri.png new file mode 100644 index 000000000..e3c7eccc3 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/add-uri.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/add-uri.snagx b/docs/_images/integrations/builtin/credentials/google/add-uri.snagx new file mode 100644 index 000000000..f848c3a80 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/add-uri.snagx differ diff --git a/docs/_images/integrations/builtin/credentials/google/application-web-application.png b/docs/_images/integrations/builtin/credentials/google/application-web-application.png new file mode 100644 index 000000000..f04969cec Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/application-web-application.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/application-web-application.snagx b/docs/_images/integrations/builtin/credentials/google/application-web-application.snagx new file mode 100644 index 000000000..90e1d9e06 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/application-web-application.snagx differ diff --git a/docs/_images/integrations/builtin/credentials/google/check-google-project.png b/docs/_images/integrations/builtin/credentials/google/check-google-project.png new file mode 100644 index 000000000..83bc79561 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/check-google-project.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/check-google-project.snagx b/docs/_images/integrations/builtin/credentials/google/check-google-project.snagx new file mode 100644 index 000000000..2921f3f0b Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/check-google-project.snagx differ diff --git a/docs/_images/integrations/builtin/credentials/google/create-credentials.png b/docs/_images/integrations/builtin/credentials/google/create-credentials.png new file mode 100644 index 000000000..07d5301a3 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/create-credentials.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/create-credentials.snagx b/docs/_images/integrations/builtin/credentials/google/create-credentials.snagx new file mode 100644 index 000000000..c88ef5c2e Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/create-credentials.snagx differ diff --git a/docs/_images/integrations/builtin/credentials/google/oauth_callback.png b/docs/_images/integrations/builtin/credentials/google/oauth_callback.png index 4d858a588..28386d6d7 100644 Binary files a/docs/_images/integrations/builtin/credentials/google/oauth_callback.png and b/docs/_images/integrations/builtin/credentials/google/oauth_callback.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.png b/docs/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.png new file mode 100644 index 000000000..34ce67451 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.snagx b/docs/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.snagx new file mode 100644 index 000000000..445c7dc21 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.snagx differ diff --git a/docs/_images/integrations/builtin/credentials/google/service-account-create-credentials.png b/docs/_images/integrations/builtin/credentials/google/service-account-create-credentials.png new file mode 100644 index 000000000..a9f65a826 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/service-account-create-credentials.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/service-account-create-credentials.snagx b/docs/_images/integrations/builtin/credentials/google/service-account-create-credentials.snagx new file mode 100644 index 000000000..abd18bb46 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/service-account-create-credentials.snagx differ diff --git a/docs/_images/integrations/builtin/credentials/google/service-account-create-key.png b/docs/_images/integrations/builtin/credentials/google/service-account-create-key.png new file mode 100644 index 000000000..d858c6f97 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/service-account-create-key.png differ diff --git a/docs/_images/integrations/builtin/credentials/google/service-account-create-key.snagx b/docs/_images/integrations/builtin/credentials/google/service-account-create-key.snagx new file mode 100644 index 000000000..e95a699d1 Binary files /dev/null and b/docs/_images/integrations/builtin/credentials/google/service-account-create-key.snagx differ diff --git a/docs/_images/integrations/creating-nodes/resource-locator.png b/docs/_images/integrations/creating-nodes/resource-locator.png new file mode 100644 index 000000000..1f5088e87 Binary files /dev/null and b/docs/_images/integrations/creating-nodes/resource-locator.png differ diff --git a/docs/_redirects b/docs/_redirects index d57068a46..b8f4377a9 100644 --- a/docs/_redirects +++ b/docs/_redirects @@ -1,3 +1,27 @@ +# 2022 UI changes + +/integrations/builtin/core-nodes/n8n-nodes-base.imapemail/ /integrations/builtin/core-nodes/n8n-nodes-base.emailimap/ + +# code schedule start nodes + +/data/data-mapping/data-item-linking/item-linking-function-node/ /data/data-mapping/data-item-linking/item-linking-code-node/ +/integrations/builtin/core-nodes/n8n-nodes-base.function/ /integrations/builtin/core-nodes/n8n-nodes-base.code/ +/integrations/builtin/core-nodes/n8n-nodes-base.functionItem/ /integrations/builtin/core-nodes/n8n-nodes-base.code/ +/integrations/builtin/core-nodes/n8n-nodes-base.functionitem/ /integrations/builtin/core-nodes/n8n-nodes-base.code/ +/integrations/builtin/core-nodes/n8n-nodes-base.cron/ /integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger/ + +# methods / vars / paired items + +/code-examples/expressions/methods/ /code-examples/methods-variables-reference/ +/code-examples/expressions/variables/ /code-examples/methods-variables-reference/ +/code-examples/javascript-functions/methods/ /code-examples/methods-variables-reference/ +/code-examples/javascript-functions/variables/ /code-examples/methods-variables-reference/ +/data/data-mapping/ /data/data-mapping/data-mapping-ui/ + +# Editor UI + +/editor-ui/ / + # Integrations menu refactor /integrations/nodes/* /integrations/builtin/app-nodes/:splat @@ -91,6 +115,7 @@ /nodes/n8n-nodes-base.activecampaigntrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.activeCampaignTrigger/ /nodes/n8n-nodes-base.acuitySchedulingTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.acuitySchedulingTrigger/ /nodes/n8n-nodes-base.acuityschedulingtrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.acuitySchedulingTrigger/ +/nodes/n8n-nodes-base.adalo/ /integrations/builtin/app-nodes.n8n-nodes-base.adalo/ /nodes/n8n-nodes-base.affinity/ /integrations/builtin/app-nodes/n8n-nodes-base.affinity/ /nodes/n8n-nodes-base.affinityTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.affinityTrigger/ /nodes/n8n-nodes-base.affinitytrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.affinityTrigger/ @@ -148,6 +173,8 @@ /nodes/n8n-nodes-base.Brandfetch/ /integrations/builtin/app-nodes/n8n-nodes-base.Brandfetch/ /nodes/n8n-nodes-base.brandfetch/ /integrations/builtin/app-nodes/n8n-nodes-base.Brandfetch/ /nodes/n8n-nodes-base.bubble/ /integrations/builtin/app-nodes/n8n-nodes-base.bubble/ +/nodes/n8n-nodes-base/calTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.calTrigger/ +/nodes/n8n-nodes-base/caltrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.caltrigger/ /nodes/n8n-nodes-base.calendlyTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.calendlyTrigger/ /nodes/n8n-nodes-base.calendlytrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.calendlyTrigger/ /nodes/n8n-nodes-base.chargebee/ /integrations/builtin/app-nodes/n8n-nodes-base.chargebee/ @@ -205,8 +232,8 @@ /nodes/n8n-nodes-base.elasticsearch/ /integrations/builtin/app-nodes/n8n-nodes-base.elasticsearch/ /nodes/n8n-nodes-base.elasticSecurity/ /integrations/builtin/app-nodes/n8n-nodes-base.elasticSecurity/ /nodes/n8n-nodes-base.elasticsecurity/ /integrations/builtin/app-nodes/n8n-nodes-base.elasticSecurity/ -/nodes/n8n-nodes-base.emailReadImap/ /integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/ -/nodes/n8n-nodes-base.emailreadimap/ /integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/ +/nodes/n8n-nodes-base.emailReadImap/ /integrations/builtin/core-nodes/n8n-nodes-base.emailimap/ +/nodes/n8n-nodes-base.emailreadimap/ /integrations/builtin/core-nodes/n8n-nodes-base.emailimap/ /nodes/n8n-nodes-base.emailSend/ /integrations/builtin/core-nodes/n8n-nodes-base.sendEmail/ /nodes/n8n-nodes-base.emailsend/ /integrations/builtin/core-nodes/n8n-nodes-base.sendEmail/ /nodes/n8n-nodes-base.emelia/ /integrations/builtin/app-nodes/n8n-nodes-base.emelia/ @@ -240,9 +267,9 @@ /nodes/n8n-nodes-base.freshworksCrm/ /integrations/builtin/app-nodes/n8n-nodes-base.freshworksCrm/ /nodes/n8n-nodes-base.freshworkscrm/ /integrations/builtin/app-nodes/n8n-nodes-base.freshworksCrm/ /nodes/n8n-nodes-base.ftp/ /integrations/builtin/core-nodes/n8n-nodes-base.ftp/ -/nodes/n8n-nodes-base.function/ /integrations/builtin/core-nodes/n8n-nodes-base.function/ -/nodes/n8n-nodes-base.functionItem/ /integrations/builtin/core-nodes/n8n-nodes-base.functionItem/ -/nodes/n8n-nodes-base.functionitem/ /integrations/builtin/core-nodes/n8n-nodes-base.functionItem/ +/nodes/n8n-nodes-base.function/ /integrations/builtin/core-nodes/n8n-nodes-base.code/ +/nodes/n8n-nodes-base.functionItem/ /integrations/builtin/core-nodes/n8n-nodes-base.code/ +/nodes/n8n-nodes-base.functionitem/ /integrations/builtin/core-nodes/n8n-nodes-base.code/ /nodes/n8n-nodes-base.getResponse/ /integrations/builtin/app-nodes/n8n-nodes-base.getResponse/ /nodes/n8n-nodes-base.getresponse/ /integrations/builtin/app-nodes/n8n-nodes-base.getResponse/ /nodes/n8n-nodes-base.getResponseTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.getResponseTrigger/ @@ -256,6 +283,7 @@ /nodes/n8n-nodes-base.gitlabTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.gitlabTrigger/ /nodes/n8n-nodes-base.gitlabtrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.gitlabTrigger/ /nodes/n8n-nodes-base.gmail/ /integrations/builtin/app-nodes/n8n-nodes-base.gmail/ +/nodes/n8n-nodes-base.gmailTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.gmailtrigger/ /nodes/n8n-nodes-base.googleAds/ /integrations/builtin/app-nodes/n8n-nodes-base.googleAds/ /nodes/n8n-nodes-base.googleads/ /integrations/builtin/app-nodes/n8n-nodes-base.googleAds/ /nodes/n8n-nodes-base.googleAnalytics/ /integrations/builtin/app-nodes/n8n-nodes-base.googleAnalytics/ @@ -268,6 +296,7 @@ /nodes/n8n-nodes-base.googlecalendar/ /integrations/builtin/app-nodes/n8n-nodes-base.googleCalendar/ /nodes/n8n-nodes-base.googleCalendarTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.googleCalendarTrigger/ /nodes/n8n-nodes-base.googlecalendartrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.googleCalendarTrigger/ +/nodes/n8n-nodes-base.googleCloudStorage/ /integrations/builtin/app-nodes/n8n-nodes-base.googlecloudstorage/ /nodes/n8n-nodes-base.googleChat/ /integrations/builtin/app-nodes/n8n-nodes-base.googleChat/ /nodes/n8n-nodes-base.googlechat/ /integrations/builtin/app-nodes/n8n-nodes-base.googleChat/ /nodes/n8n-nodes-base.googleCloudNaturalLanguage/ /integrations/builtin/app-nodes/n8n-nodes-base.googleCloudNaturalLanguage/ @@ -393,6 +422,7 @@ /nodes/n8n-nodes-base.merge/ /integrations/builtin/core-nodes/n8n-nodes-base.merge/ /nodes/n8n-nodes-base.messageBird/ /integrations/builtin/app-nodes/n8n-nodes-base.messageBird/ /nodes/n8n-nodes-base.messagebird/ /integrations/builtin/app-nodes/n8n-nodes-base.messageBird/ +/nodes/n8n-nodes-base.metabase/ /integrations/builtin/app-nodes/n8n-nodes-base.metabase/ /nodes/n8n-nodes-base.microsoftDynamicsCrm/ /integrations/builtin/app-nodes/n8n-nodes-base.microsoftDynamicsCrm/ /nodes/n8n-nodes-base.microsoftdynamicscrm/ /integrations/builtin/app-nodes/n8n-nodes-base.microsoftDynamicsCrm/ /nodes/n8n-nodes-base.microsoftExcel/ /integrations/builtin/app-nodes/n8n-nodes-base.microsoftExcel/ @@ -472,6 +502,7 @@ /nodes/n8n-nodes-base.pipedriveTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.pipedriveTrigger/ /nodes/n8n-nodes-base.pipedrivetrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.pipedriveTrigger/ /nodes/n8n-nodes-base.plivo/ /integrations/builtin/app-nodes/n8n-nodes-base.plivo/ +/nodes/n8n-nodes-base.postbin/ /integrations/builtin/app-nodes/n8n-nodes-base.postbin/ /nodes/n8n-nodes-base.postgres/ /integrations/builtin/app-nodes/n8n-nodes-base.postgres/ /nodes/n8n-nodes-base.postHog/ /integrations/builtin/app-nodes/n8n-nodes-base.postHog/ /nodes/n8n-nodes-base.postmarkTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.postmarkTrigger/ @@ -521,6 +552,10 @@ /nodes/n8n-nodes-base.segment/ /integrations/builtin/app-nodes/n8n-nodes-base.segment/ /nodes/n8n-nodes-base.sendGrid/ /integrations/builtin/app-nodes/n8n-nodes-base.sendGrid/ /nodes/n8n-nodes-base.sendgrid/ /integrations/builtin/app-nodes/n8n-nodes-base.sendGrid/ +/nodes/n8n--nodes-base.sendInBlue/ /integrations/builtin/app-nodes/n8n-nodes-base.sendInBlue/ +/nodes/n8n--nodes-base.sendinblue/ /integrations/builtin/app-nodes/n8n-nodes-base.sendinblue/ +/nodes/n8n--nodes-base.sendInBlue/ /integrations/builtin/trigger-nodes/n8n-nodes-base.sendInBlueTrigger/ +/nodes/n8n--nodes-base.sendinblue/ /integrations/builtin/trigger-nodes/n8n-nodes-base.sendinbluetrigger/ /nodes/n8n-nodes-base.sendy/ /integrations/builtin/app-nodes/n8n-nodes-base.sendy/ /nodes/n8n-nodes-base.sentryIo/ /integrations/builtin/app-nodes/n8n-nodes-base.sentryIo/ /nodes/n8n-nodes-base.sentryio/ /integrations/builtin/app-nodes/n8n-nodes-base.sentryIo/ @@ -610,7 +645,7 @@ /nodes/n8n-nodes-base.wisetrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.wiseTrigger/ /nodes/n8n-nodes-base.wooCommerce/ /integrations/builtin/app-nodes/n8n-nodes-base.wooCommerce/ /nodes/n8n-nodes-base.woocommerce/ /integrations/builtin/app-nodes/n8n-nodes-base.wooCommerce/ -/trigger-nodes/n8n-nodes-base.wooCommerceTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.wooCommerceTrigger/ +/nodes/n8n-nodes-base.wooCommerceTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.wooCommerceTrigger/ /nodes/n8n-nodes-base.woocommercetrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.wooCommerceTrigger/ /nodes/n8n-nodes-base.wordpress/ /integrations/builtin/app-nodes/n8n-nodes-base.wordpress/ /nodes/n8n-nodes-base.workableTrigger/ /integrations/builtin/trigger-nodes/n8n-nodes-base.workableTrigger/ diff --git a/docs/code-examples/console-log.md b/docs/code-examples/console-log.md new file mode 100644 index 000000000..25e087b42 --- /dev/null +++ b/docs/code-examples/console-log.md @@ -0,0 +1,14 @@ +# Using console.log in the Code node + +You can use `console.log()` in the Code node to help when writing and debugging your code. + +For help opening your browser console, refer to [this guide by Balsamiq](https://balsamiq.com/support/faqs/browserconsole/){:target=_blank .external-link}. + +For technical information on `console.log()`, refer to the [MDN developer docs](https://developer.mozilla.org/en-US/docs/Web/API/Console/log){:target=_blank .external-link}. + +For example, copy the following code into a Code node, then open your console and run the node: + +```js +let a = "apple"; +console.log(a); +``` diff --git a/docs/code-examples/expressions/index.md b/docs/code-examples/expressions/index.md index a823974b4..c7990c6de 100644 --- a/docs/code-examples/expressions/index.md +++ b/docs/code-examples/expressions/index.md @@ -27,7 +27,7 @@ To use an expression to set a parameter value: 3. Write your expression in the expression editor. You can browse some of the available data in the **Variable selector**. All expressions have the format `{{ your expression here }}`. -### Example: get data from webhook body +### Example: Get data from webhook body Consider the following scenario: you have a webhook trigger that receives data through the webhook body. You want to extract some of that data for use in the workflow. @@ -66,7 +66,7 @@ This expression: 2. Finds the value of `city` (in this example, "New York"). Note that this example uses JMESPath syntax to query the JSON data. You can also write this expression as `{{$json['body']['city']}}`. -### Example: writing longer JavaScript +### Example: Writing longer JavaScript An expression contains one line of JavaScript. This means you can'd do things like variable assignments or multiple standalone operations. diff --git a/docs/code-examples/expressions/methods.md b/docs/code-examples/expressions/methods.md deleted file mode 100644 index a375065ca..000000000 --- a/docs/code-examples/expressions/methods.md +++ /dev/null @@ -1,8 +0,0 @@ -# Custom methods - ---8<-- "_snippets/code-examples/methods-list.md" - - - - - diff --git a/docs/code-examples/expressions/variables.md b/docs/code-examples/expressions/variables.md deleted file mode 100644 index 1538b551d..000000000 --- a/docs/code-examples/expressions/variables.md +++ /dev/null @@ -1,25 +0,0 @@ -# Custom variables - ---8<-- "_snippets/code-examples/variables-list.md" - -## Examples - - -### $workflow - -Gives information about the current workflow. - -```js -// Boolean. Whether the workflow is active (true) or not (false) -$workflow.active -// Number. The workflow ID. -$workflow.id -// String. The workflow name. -$workflow.name -``` - -### $resumeWebhookUrl - -The webhook URL to call to resume a [waiting](/integrations/builtin/core-nodes/n8n-nodes-base.wait/) workflow. - -See the [Wait > On webhook call](/integrations/builtin/core-nodes/n8n-nodes-base.wait/#webhook-call) documentation to learn more. diff --git a/docs/code-examples/index.md b/docs/code-examples/index.md index ce4826bef..f622f9adb 100644 --- a/docs/code-examples/index.md +++ b/docs/code-examples/index.md @@ -1,18 +1,19 @@ -# Overview +# Code in n8n There are two places in n8n where you need to use code: * In [expressions](/code-examples/expressions/), for example programmatically setting the value of a field based on incoming data. -* In the [function node](/integrations/builtin/core-nodes/n8n-nodes-base.function/), when you need to add JavaScript to your workflow. +* In the [Code node](/integrations/builtin/core-nodes/n8n-nodes-base.code/), when you need to add JavaScript to your workflow. This section covers: -* Expressions: +* Built-in [methods and variables](/code-examples/methods-variables-reference/). +* Expressions examples: * [Introduction to expressions in n8n](/code-examples/expressions/). - * Built in [methods](/code-examples/expressions/methods/) and [variables](/code-examples/expressions/variables/). * Supported libraries: [Luxon](/code-examples/expressions/luxon/) (for data and time) and [JMESPath](/code-examples/expressions/jmespath/) (for working with JSON). -* JavaScript: +* JavaScript examples: * [Introduction to JavaScript in n8n](/code-examples/javascript-functions/). - * Built in [methods](/code-examples/javascript-functions/methods/) and [variables](/code-examples/javascript-functions/variables/). + * Supported libraries: [Luxon](/code-examples/javascript-functions/luxon/) (for data and time) and [JMESPath](/code-examples/javascript-functions/jmespath/) (for working with JSON). * [Checking incoming data](/code-examples/javascript-functions/check-incoming-data/). - * [Get the number of items returned by the last node](/code-examples/javascript-functions/number-items-last-node/). \ No newline at end of file + * [Get the number of items returned by the last node](/code-examples/javascript-functions/number-items-last-node/). + * Working with binary data: [Get the binary data buffer](/code-examples/javascript-functions/get-binary-data-buffer/) and [Split binary file data into individual items](/code-examples/javascript-functions/split-binary-file-data/). diff --git a/docs/code-examples/javascript-functions/index.md b/docs/code-examples/javascript-functions/index.md index 04ebbc888..6e2da642e 100644 --- a/docs/code-examples/javascript-functions/index.md +++ b/docs/code-examples/javascript-functions/index.md @@ -1,9 +1,9 @@ -# JavaScript Code Snippets +# JavaScript examples In n8n, you can write custom JavaScript code snippets to add, remove, and update the data you receive from a node. You can also use code snippets to modify the data structure of the data returned by a node. !!! note "Keep in mind" - We are using Set node for illustrating expressions here. However, you can use the code snippets as an expression in any node. To do that, click on the gears icon next to a field and click on ***Add Expression***. + We are using Set node for illustrating expressions here. However, you can use the code snippets as an expression in any node. To do that, click on the gears icon next to a field and click on **Add Expression**. For each section, we'll share code snippets that can be used in the function node as well as the expressions. You can read more about [Expressions](/code-examples/expressions/) and adding code snippets to the [Function](/integrations/builtin/core-nodes/n8n-nodes-base.function/) node in our documentation. diff --git a/docs/code-examples/javascript-functions/methods.md b/docs/code-examples/javascript-functions/methods.md deleted file mode 100644 index 0f19e5cd3..000000000 --- a/docs/code-examples/javascript-functions/methods.md +++ /dev/null @@ -1,80 +0,0 @@ -# Custom methods - ---8<-- "_snippets/code-examples/methods-list.md" - -### $evaluateExpression(expression: string, itemIndex: number) - -Evaluates a given string as expression. -If no `itemIndex` is provided it uses by default in the Function-Node the data of item 0 and -in the Function Item-Node the data of the current item. - -Example: - -```javascript -items[0].json.variable1 = $evaluateExpression('{{1+2}}'); -items[0].json.variable2 = $evaluateExpression($node["Set"].json["myExpression"], 1); - -return items; -``` - - -### $items(nodeName?: string, outputIndex?: number, runIndex?: number) - -This gives access to all the items of current or parent nodes. If no parameters are supplied, -it returns all the items of the current node. -If a node-name is given, it returns the items the node output on its first output -(index: 0, most nodes only have one output, exceptions are IF and Switch-Node) on -its last run. - -Example: - -```typescript -// Returns all the items of the current node and current run -const allItems = $items(); - -// Returns all items the node "IF" outputs (index: 0 which is Output "true" of its most recent run) -const allItems = $items("IF"); - -// Returns all items the node "IF" outputs (index: 0 which is Output "true" of the same run as current node) -const allItems = $items("IF", 0, $runIndex); - -// Returns all items the node "IF" outputs (index: 1 which is Output "false" of run 0 which is the first run) -const allItems = $items("IF", 1, 0); -``` - -### $item(index: number, runIndex?: number) - -This method allows you to return an item at a specific index. The index is zero-based. Hence, `$item(0)` will return the first item, `$item(1)` the second one, and so on. Refer to [this](/integrations/builtin/core-nodes/n8n-nodes-base.function/) documentation to learn more. - -Example: - -```typescript -// Returns the first item returned by the Example node -const firstItem = $item(0).$node["Example Node"]; - -// Returns the second item returned by the Example node -const secondItem = $item(1).$node["Example Node"]; -``` - -Refer to this [example workflow](https://n8n.io/workflows/1330) to learn how this method can be used. - -### $node - -Returns the data of a specified node. Similar to `$item`, with the difference that it always returns the data of the first output and the last run of the node. - -```typescript -// Returns the fileName of binary property "data" of Node "HTTP Request" -const fileName = $node["HTTP Request"].binary["data"]["fileName"]}} - -// Returns the context data "noItemsLeft" of Node "SplitInBatches" -const noItemsLeft = $node["SplitInBatches"].context["noItemsLeft"]; - -// Returns the value of the JSON data property "myNumber" of Node "Set" -const myNumber = $node["Set"].json['myNumber']; - -// Returns the value of the parameter "channel" of Node "Slack" -const channel = $node["Slack"].parameter["channel"]; - -// Returns the index of the last run of Node "HTTP Request" -const runIndex = $node["HTTP Request"].runIndex}} -``` diff --git a/docs/code-examples/javascript-functions/variables.md b/docs/code-examples/javascript-functions/variables.md deleted file mode 100644 index 75fa0260c..000000000 --- a/docs/code-examples/javascript-functions/variables.md +++ /dev/null @@ -1,37 +0,0 @@ -# Custom variables - ---8<-- "_snippets/code-examples/variables-list.md" - -## Examples - -### $executionId - -Contains the unique ID of the current workflow execution. - -```typescript -const executionId = $executionId; - -return [{json:{executionId}}]; -``` - -### $runIndex - -Contains the index of the current run of the node. - -```typescript -// Returns all items the node "IF" outputs (index: 0 which is Output "true" of the same run as current node) -const allItems = $items("IF", 0, $runIndex); -``` - -### $workflow - -Gives information about the current workflow. - -```js -// Boolean. Whether the workflow is active (true) or not (false) -$workflow.active -// Number. The workflow ID. -$workflow.id -// String. The workflow name. -$workflow.name -``` diff --git a/docs/code-examples/methods-variables-examples/all.md b/docs/code-examples/methods-variables-examples/all.md new file mode 100644 index 000000000..90bdff64c --- /dev/null +++ b/docs/code-examples/methods-variables-examples/all.md @@ -0,0 +1,30 @@ +# `$("").all(branchIndex?: number, runIndex?: number)` + +This gives access to all the items of the current or parent nodes. If you don't supply any parameters, it returns all the items of the current node. + +## Getting items + +```typescript +// Returns all the items of the given node and current run +const allItems = $("").all(); + +// Returns all items the node "IF" outputs (index: 0 which is Output "true" of its most recent run) +const allItems = $("IF").all(); + +// Returns all items the node "IF" outputs (index: 0 which is Output "true" of the same run as current node) +const allItems = $("IF").all(0, $runIndex); + +// Returns all items the node "IF" outputs (index: 1 which is Output "false" of run 0 which is the first run) +const allItems = $("IF").all(1, 0); +``` + +## Accessing item data + +Get all items output by a previous node, and log out the data they contain: + +```typescript +previousNodeData = $("").all(); +for(let i=0; i On webhook call](/integrations/builtin/core-nodes/n8n-nodes-base.wait/#webhook-call) documentation to learn more. diff --git a/docs/code-examples/methods-variables-examples/get-workflow-static-data.md b/docs/code-examples/methods-variables-examples/get-workflow-static-data.md new file mode 100644 index 000000000..0ae278a2d --- /dev/null +++ b/docs/code-examples/methods-variables-examples/get-workflow-static-data.md @@ -0,0 +1,36 @@ +# `$getWorkflowStaticData(type)` + +This gives access to the static workflow data. + +!!! note "Experimental feature" + Static data isn't available when testing workflows. The workflow must be active and called by a trigger or webhook to save static data. + +You can save data directly in the workflow. This data should be small. + +As an example: you can save a timestamp of the last item processed from +an RSS feed or database. It will always return an object. Properties can then read, delete or +set on that object. When the workflow execution succeeds, n8n checks automatically if the data +has changed and saves it, if necessary. + +There are two types of static data, "global" and "node". Global static data is the +same in the whole workflow. Every node in the workflow can access it. The node static data is unique to the node. Only the node that set it can retrieve it again. + +Example: + +```javascript +// Get the global workflow static data +const staticData = getWorkflowStaticData('global'); +// Get the static data of the node +const staticData = getWorkflowStaticData('node'); + +// Access its data +const lastExecution = staticData.lastExecution; + +// Update its data +staticData.lastExecution = new Date().getTime(); + +// Delete data +delete staticData.lastExecution; +``` + + diff --git a/docs/code-examples/methods-variables-examples/index.md b/docs/code-examples/methods-variables-examples/index.md new file mode 100644 index 000000000..8b20877ea --- /dev/null +++ b/docs/code-examples/methods-variables-examples/index.md @@ -0,0 +1,3 @@ +# Overview + +n8n provides built-in methods and variables for working with data and accessing n8n data. This section provides usage examples. diff --git a/docs/code-examples/methods-variables-examples/node.md b/docs/code-examples/methods-variables-examples/node.md new file mode 100644 index 000000000..21cf3bdac --- /dev/null +++ b/docs/code-examples/methods-variables-examples/node.md @@ -0,0 +1,18 @@ +# `$("").item` + +!!! info "Not avaialble in Function node" + `$("").item` isn't available in the Function node. + + +Returns the data of a specified node. + +```typescript +// Returns the fileName of binary property "data" of Node "HTTP Request" +const fileName = $("HTTP Request").item.binary["data"]["fileName"]}} + +// Returns the value of the JSON data property "myNumber" of Node "Set" +const myNumber = $("Set").item.json['myNumber']; + +// Returns the value of the parameter "channel" of Node "Slack" +const channel = $("Slack").item.parameter["channel"]; +``` diff --git a/docs/code-examples/methods-variables-examples/run-index.md b/docs/code-examples/methods-variables-examples/run-index.md new file mode 100644 index 000000000..496d190b6 --- /dev/null +++ b/docs/code-examples/methods-variables-examples/run-index.md @@ -0,0 +1,8 @@ +# `$runIndex` + +Contains the index of the current run of the node. + +```typescript +// Returns all items the node "IF" outputs (index: -1) +const allItems = $("").all(branchIndex?, runIndex?)` | Returns all items from a given node. | :white_check_mark: | +| `$("").first(branchIndex?, runIndex?)` | The first item output by the given node | :white_check_mark: | +| `$("").last(branchIndex?, run Index?)` | The last item output by the given node. | :white_check_mark: | +| `$("").item` | The linked item. This is the item in the specified node used to produce the current item. Refer to [Item linking](/data/data-mapping/data-item-linking/) for more information on item linking. | :x: | +| `$("").params` | Object containing the query settings of the given node. This includes data such as the operation it ran, result limits, and so on. | :white_check_mark: | +| `$("").context` | Only available when working with the Split in Batches node. Provides information about what's happening in the node, allowing you to see if the node is still processing items. | :white_check_mark: | +| `$("").itemMatching(currentNodeinputIndex)` | Use instead of `$("").item` in the Function node if you need to trace back from an input item. | :white_check_mark: | + + + + + + + +## Date and time + +| Method | Description | Available in Function node? | +| ------ | ----------- | :-------------------------: | +| `$now` | A Luxon object containing the current timestamp. Equivalent to `DateTime.now()`. | :white_check_mark: | +| `$today` | A Luxon object containing the current timestamp, rounded down to the day. Equivalent to `DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 })`. | :white_check_mark: | + + +## n8n metadata + +This includes: + +* Access to n8n environment variables for self-hosted n8n. +* Metadata about workflows, executions, and nodes. + +| Method | Description | Available in Function node? | +| ------ | ----------- | :-------------------------: | +| `$env` | Contains [environment variables](/hosting/environment-variables/). | :white_check_mark: | +| `$execution.id` | The unique ID of the current workflow execution. | :white_check_mark: | +| `$execution.mode` | Whether the execution was triggered automatically, or by manually running the workflow. Possible values are `test` and `production`. | :white_check_mark: | +| `$execution.resumeUrl` | The webhook URL to call to resume a workflow waiting at a [Wait node](/integrations/builtin/core-nodes/n8n-nodes-base.wait/). | :white_check_mark: | +| `$getWorkflowStaticData(type)` | View an [example](/code-examples/methods-variables-examples/get-workflow-static-data/). Static data isn't available when testing workflows. The workflow must be active and called by a trigger or webhook to save static data. This gives access to the static workflow data. | :white_check_mark: | +| `$itemIndex` | The index of an item in a list of items. | :x: | +| `$prevNode.name` | The name of the node that the current input came from. When using the Merge node, note that `$prevNode` always uses the first input connector. | :white_check_mark: | +| `$prevNode.outputIndex` | The index of the output connector that the current input came from. Use this when the previous node had multiple outputs (such as an If or Switch node). When using the Merge node, note that `$prevNode` always uses the first input connector. | :white_check_mark: | +| `$prevNode.runIndex` | The run of the previous node that generated the current input. When using the Merge node, note that `$prevNode` always uses the first input connector. | :white_check_mark: | +| `$runIndex` | How many times n8n has executed the current node. Zero-based (the first run is 0, the second is 1, and so on). | :white_check_mark: | +| `$workflow.active` | Whether the workflow is active (true) or not (false). | :white_check_mark: | +| `$workflow.id` | The workflow ID. | :white_check_mark: | +| `$workflow.name` | The workflow name. | :white_check_mark: | + + +## Advanced + +| Method | Description | Available in Function node? | +| ------ | ----------- | :-------------------------: | +| `$evaluateExpression` | Evaluates a string as an expression | :white_check_mark: | +| `$jmespath()` | Perform a search on a JSON object using JMESPath. | :white_check_mark: | diff --git a/docs/contributing.md b/docs/contributing.md index f8200dd9b..7d28a533b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,25 +1,8 @@ -# How can I contribute? +# How can you contribute? There are a several ways in which you can contribute to n8n, depending on your skills and interests. Each form of contribution is valuable to us! -## Contributor quick start - -Here is a quick list of the contributions we are looking for: - -- Build community nodes -- Write an n8n tutorial -- Host an n8n event (virtual or locally) -- Write for our docs -- Create workflow templates -- Write a review -- Participate on our support forum - -To start contributing or to get ideas of what to do, check out our [Contributor board on GitHub](https://github.com/orgs/n8n-io/projects/3){:target=_blank class=.external-link}. If there is a project you want on the board, please assign it to yourself and start contributing! - -Keep reading for more ideas on contributions. - - -## Share some love +## Share some love: review us - Star n8n on [GitHub](https://github.com/n8n-io/n8n){:target=_blank class=.external-link} and [Docker Hub](https://hub.docker.com/r/n8nio/n8n){:target=_blank class=.external-link}. - Follow us on [Twitter](https://twitter.com/n8n_io){:target=_blank class=.external-link}, [LinkedIn](https://www.linkedin.com/company/28491094), and [Facebook](https://www.facebook.com/n8nio/){:target=_blank class=.external-link}. @@ -51,14 +34,12 @@ To share a workflow, follow these steps: 1. Sign in to [n8n.io](https://n8n.io/login){:target=_blank class=.external-link}. 2. Open the [workflows](https://n8n.io/workflows){:target=_blank class=.external-link} page. -3. Click on the **+ Share New Workflow** button. -4. Enter the name of your workflow in the **Name** field. -The name should be short and descriptive, so that other users can understand the purpose of the workflow at a glance. -5. Enter a detailed description of the workflow in the **Description** field. -In the description you should add a screenshot of the workflow and briefly explain what the nodes used in the workflow do. +3. Select **+ Share New Workflow**. +4. Enter the name of your workflow in the **Name** field. The name should be short and descriptive, so that other users can understand the purpose of the workflow at a glance. +5. Enter a detailed description of the workflow in the **Description** field. Add a screenshot of the workflow and briefly explain what the nodes used in the workflow do. 6. In your n8n instance, select all the nodes in your workflow (Ctrl + A or Cmd + A) and copy them (Ctrl + C or Cmd + C). 7. Back on the workflows page, delete the existing code in the **Workflow Code** field and paste your workflow in it (Ctrl + V or Cmd + V). -8. Click on the **Publish Workflow to Share** button to share your workflow. +8. Select **Publish Workflow to Share** to share your workflow. See the above steps in action in this video: @@ -70,13 +51,16 @@ See the above steps in action in this video: --> +## Build a node + +Create an integration for a third party service. Check out [the node creation docs](/integrations/creating-nodes/) for guidance on how to create and publish a community node. + ## Contribute to the code There are different ways in which you can contribute to the n8n code base: - Fix [issues](https://github.com/n8n-io/n8n/issues){:target=_blank class=.external-link} reported on GitHub. The [CONTRIBUTING guide](https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md){:target=_blank class=.external-link} will help you get your development environment ready in minutes. - Add additional functionality to an existing third party integration. -- Create an integration for a third party service. Check out [the node creation docs](/integrations/creating-nodes/) for guidance on how to create a node. - Add a new feature to n8n. ## Contribute to the docs diff --git a/docs/courses/level-one/chapter-1.md b/docs/courses/level-one/chapter-1.md index 09477b886..99cf99366 100644 --- a/docs/courses/level-one/chapter-1.md +++ b/docs/courses/level-one/chapter-1.md @@ -30,8 +30,10 @@ The panel contains the following sections: - *Admin Panel*: Access the management Dashboard (for n8n Cloud users). - *Workflows*: Contains operations for creating and editing workflows. +- *Templates*: Contains pre-built workflows that can be searched. - *Credentials*: Contains operations for creating credentials. - *Executions*: Contains information about your workflow executions. +- *Settings*: Contains editable configuration for the account and other things. - *Help*: Contains resources around n8n product and community.
Editor UI left-side menu
Editor UI left-side menu
diff --git a/docs/courses/level-one/chapter-2.md b/docs/courses/level-one/chapter-2.md index 49ca9ec64..f65927c34 100644 --- a/docs/courses/level-one/chapter-2.md +++ b/docs/courses/level-one/chapter-2.md @@ -27,10 +27,10 @@ The *Hacker News node* has several parameters that need to be configured in orde - *Resource:* All
This resource selects all data records (articles). -- *Operation:* Get All
+- *Operation:* Get Many
This operation fetches all the selected articles. - *Limit:* 10
-This parameter sets a limit to how many results are returned by the Get All operation. +This parameter sets a limit to how many results are returned by the Get Many operation. - *Additional fields > Add Field > Keyword:* automation
Additional fields are options that you can add to certain nodes to make your request more specific or filter the results. In our case, we want to get only articles that include the keyword “automation”.
@@ -103,7 +103,7 @@ The node window displays more information about the node execution: This field displays the number of items (records) that are returned by the node request. In our case, it's expected to be 10, since this is the limit we set in the node. But if you don't set a limit, it's useful to see how many records are actually returned. - Next to the *Items* information, notice a small orange *i* icon. If you hover on it, you'll get two more pieces of information: ***Start Time*** (when the node execution started) and ***Execution Time*** (how long it took for the node to return the results from the moment it started executing). *Start Time* and *Execution Time* can provide insights into the performance of each individual node. -- In the bottom right corner right under the node window, there is a reference link to the node's **documentation**. Check it out if you run into trouble or are not sure how to configure the node's parameters. +- Under the node name beside the **Parameters** tab, there is a link to the node's **Docs**. Check it out if you run into trouble or are not sure how to configure the node's parameters. !!! warning "Error in nodes" diff --git a/docs/courses/level-one/chapter-5/chapter-5.1.md b/docs/courses/level-one/chapter-5/chapter-5.1.md index d43ed8f7a..358223afa 100644 --- a/docs/courses/level-one/chapter-5/chapter-5.1.md +++ b/docs/courses/level-one/chapter-5/chapter-5.1.md @@ -31,7 +31,7 @@ In the left panel, select: - *Headers > Add Header:* - *Name:* `unique_id` - *Value:* The Unique ID your received in the email when you signed up for this course. -- *Authentication:* Header Auth
+- *Authentication > Generic Credential Type > Generic Auth Type:* Header Auth
This option requires credentials to allow you to access the data. !!! note "Credentials" diff --git a/docs/courses/level-one/chapter-5/chapter-5.3.md b/docs/courses/level-one/chapter-5/chapter-5.3.md index 16eb6617e..3d791c55b 100644 --- a/docs/courses/level-one/chapter-5/chapter-5.3.md +++ b/docs/courses/level-one/chapter-5/chapter-5.3.md @@ -15,7 +15,7 @@ Back to your workflow, remove the connection between the *HTTP Request* node and In the *IF* node window click on *Add Condition* > *string* and configure the parameters: - *Value 1*: Current Node > Input Data > JSON > orderStatus → `{{$json["orderStatus"]}}`
-To select this value, click on the wheel icon “Add Expression” on the right side of the Value 1 field. +To select this value, click the **Expression** tab on the right side of the Value 1 field. !!! note "Expressions" An expression is a string of characters and symbols in a programming language that represents a value depending upon its input. In n8n workflows, you can use expressions in a node to refer to another node for input data. In our example, the IF node references the data output by the HTTP Request node. diff --git a/docs/courses/level-one/chapter-5/chapter-5.5.md b/docs/courses/level-one/chapter-5/chapter-5.5.md index b36f90e1e..89e1c325c 100644 --- a/docs/courses/level-one/chapter-5/chapter-5.5.md +++ b/docs/courses/level-one/chapter-5/chapter-5.5.md @@ -29,15 +29,15 @@ In n8n, the data that is passed between nodes is an array of objects with the fo // Any kind of JSON data is allowed. So arrays and the data being deeply nested is fine. json: { // The actual data n8n operates on (required) // This data is only an example it could be any kind of JSON data - jsonKeyName: 'keyValue', - anotherJsonKey: { - lowerLevelJsonKey: 1 + apple: 'beets', + carrot: { + dill: 1 } }, // Binary data of item. The most items in n8n do not contain any (optional) binary: { - // The key-name "binaryKeyName" is only an example. Any kind of key-name is possible. - binaryKeyName: { + // The key-name "apple" is only an example. Any kind of key-name is possible. + apple-picture: { data: '....', // Base64 encoded binary data (required) mimeType: 'image/png', // Optional but should be set if possible (optional) fileExtension: 'png', // Optional but should be set if possible (optional) diff --git a/docs/courses/level-one/chapter-5/chapter-5.8.md b/docs/courses/level-one/chapter-5/chapter-5.8.md index a14a027b3..972302b30 100644 --- a/docs/courses/level-one/chapter-5/chapter-5.8.md +++ b/docs/courses/level-one/chapter-5/chapter-5.8.md @@ -25,7 +25,7 @@ The *Workflow Executions* window displays a table with the following information * _Running Time:_ The duration it took the workflow to execute !!! note "Workflow execution status" - In the *Workflow Executions* window you can filter the displayed executions by workflow and by status (*All*, *Error*, *Running*, or *Success*).\ + In the **Workflow Executions** window you can filter the displayed executions by workflow and by status (**All**, **Error**, **Running**, or **Success**). The information displayed here depends on what workflows and executions you set up in *Workflow Settings* to be saved. diff --git a/docs/courses/level-one/index.md b/docs/courses/level-one/index.md index 070245c50..5c48c5edb 100644 --- a/docs/courses/level-one/index.md +++ b/docs/courses/level-one/index.md @@ -1,4 +1,4 @@ -# Introduction +# Level one: Introduction Welcome to the **n8n Course Level 1**! diff --git a/docs/courses/level-two/chapter-1.md b/docs/courses/level-two/chapter-1.md index 071dc6191..ecf6be616 100644 --- a/docs/courses/level-two/chapter-1.md +++ b/docs/courses/level-two/chapter-1.md @@ -62,12 +62,12 @@ Now that you are familiar with the n8n data structure, you can use it to create ```javascript return [ - { - json: { - key: 'value', - } - } - ]; + { + json: { + apple: 'beets', + } + } +]; ``` For example, the array of objects representing the Ninja turtles would look like this in the Function node: @@ -131,7 +131,7 @@ In a Function node, create an array of objects named `myContacts` that contains ## Referencing node data with the Function node -Just like you can use [expressions](/code-examples/expressions/){:target="_blank" .external} to reference data from other nodes, you can also use some [methods](/code-examples/expressions/methods/){:target="_blank" .external} and [variables](/code-examples/expressions/variables/){:target="_blank" .external} in the Function node. +Just like you can use [expressions](/code-examples/expressions/) to reference data from other nodes, you can also use some [methods and variables](/code-examples/methods-variables-reference/) in the Function node. ### Exercise diff --git a/docs/courses/level-two/index.md b/docs/courses/level-two/index.md index e681cad9f..1a5d86bc2 100644 --- a/docs/courses/level-two/index.md +++ b/docs/courses/level-two/index.md @@ -1,4 +1,4 @@ -# Introduction +# Level two: Introduction Welcome to the **n8n Course Level 2**! diff --git a/docs/credentials/add-edit-credentials.md b/docs/credentials/add-edit-credentials.md new file mode 100644 index 000000000..e4e7de13a --- /dev/null +++ b/docs/credentials/add-edit-credentials.md @@ -0,0 +1,10 @@ +# Create and edit credentials + +You can get to the credential modal by either: + +* Opening the left menu, then selecting **Credentials** > **New** and browsing for the service you want to connect to. +* Selecting **Create New** in the **Credential** dropdown in a node. + +Once in the credential modal, enter the details required by your service. Refer to your service's page in the [credentials library](/integrations/builtin/credentials/) for guidance. + +When you save a credential, n8n tests it to confirm it works. diff --git a/docs/credentials/credential-sharing.md b/docs/credentials/credential-sharing.md new file mode 100644 index 000000000..274bd29fc --- /dev/null +++ b/docs/credentials/credential-sharing.md @@ -0,0 +1,27 @@ +# Credential sharing + +!!! info "Feature availability" + * Limited Cloud plans. Refer to [Cloud Pricing](https://n8n.io/pricing/){:target=_blank .external-link} for more information. + * Not available outside Cloud. + +Credential sharing allows you to share a credential you created with other users in the same n8n workspace as you. The other users can then use the credential in their workflows. They can't access or edit the credential details. + +To use credential sharing, you must enable [user management](/hosting/user-management/). + +## Share a credential + +1. Open the left menu and select **Credentials**. n8n shows a list of your credentials. +2. Select the credential you want to share. n8n opens the credential modal. +3. Select **Sharing**. +4. In **Add people**, browse or search for the user you want to share the credential with. +5. Select a user. + +## Remove access to a credential + +To unshare a credential: + +1. Open the left menu and select **Credentials**. n8n shows a list of your credentials. +2. Select the credential you want to share. n8n opens the credential modal. +3. Select **Sharing**. +4. Select **Options** ![Options menu icon](/_images/common-icons/three-dot-options-menu.png) on the user you want to remove. +5. Select **Remove**. diff --git a/docs/credentials/index.md b/docs/credentials/index.md new file mode 100644 index 000000000..722fc2e83 --- /dev/null +++ b/docs/credentials/index.md @@ -0,0 +1,11 @@ +# Credentials + +Credentials are private pieces of information issued by apps and services to authenticate you as a user and allow you to connect and share information between the app or service and the n8n node. + +Access the credentials UI by opening the left menu and selecting **Credentials**. n8n lists credentials you created on the **My credentials** tab. The **All credentials** tab shows all credentials you can use, included credentials shared with you by other users. + +* [Create and edit credentials](/credentials/add-edit-credentials/). +* Learn about [credential sharing](/credentials/credential-sharing/). +* Find information on setting up credentials for your services in the [credentials library](/integrations/builtin/credentials/). + + diff --git a/docs/data/code.md b/docs/data/code.md index 12600b748..417ad9426 100644 --- a/docs/data/code.md +++ b/docs/data/code.md @@ -4,13 +4,13 @@ A function is a block of code designed to perform a certain task. In n8n, you can write custom JavaScript code snippets to add, remove, and update the data you receive from a node. -The [Function](/integrations/builtin/core-nodes/n8n-nodes-base.function/) and [Function Item](/integrations/builtin/core-nodes/n8n-nodes-base.functionItem/) nodes are the most powerful in n8n. Both nodes work very similarly, they give you access to the incoming data and you can manipulate it. With these nodes you can implement any function you want using JavaScript code. +The [Function](/integrations/builtin/core-nodes/n8n-nodes-base.function/) and [Function Item](/integrations/builtin/core-nodes/n8n-nodes-base.functionItem/) nodes are the most powerful in n8n. Both nodes work similarly: they give you access to the incoming data and you can manipulate it. With these nodes you can implement any function you want using JavaScript code. -The code of the **Function node** gets executed only once. The node receives the full items (JSON and binary data) as an array and expects an array of items as a return value. The items returned can be totally different from the incoming ones. So it is not only possible to remove and edit existing items, but also to add or return totally new ones. +The code of the **Function node** gets executed once. The node receives the full items (JSON and binary data) as an array and expects an array of items as a return value. The items returned can be totally different from the incoming ones. It's possible to remove and edit existing items, and also to add or return totally new ones. -The code of the **Function Item node** gets executed once for every item. The node receives one item (just the JSON data) at a time as input. As a return value, it expects the JSON data of one single item. That makes it possible to add, remove, and edit JSON properties of items, but it is not possible to add new or remove existing items. Accessing and changing binary data is only possible via the methods `getBinaryData` and `setBinaryData`. +The code of the **Function Item node** gets executed once for every item. The node receives one item (just the JSON data) at a time as input. As a return value, it expects the JSON data of one single item. That makes it possible to add, remove, and edit JSON properties of items, but it's not possible to add new or remove existing items. Accessing and changing binary data is only possible using the methods `getBinaryData` and `setBinaryData`. -Both the Function node and Function Item node support promises. So instead of returning the item or items directly, it is also possible to return a promise which resolves accordingly. +Both the Function node and Function Item node support promises. Instead of returning the item or items directly, it's also possible to return a promise which resolves accordingly. Here is a comparative overview of the Function and Function Item nodes: diff --git a/docs/data/data-mapping.md b/docs/data/data-mapping.md deleted file mode 100644 index 469f82e09..000000000 --- a/docs/data/data-mapping.md +++ /dev/null @@ -1,43 +0,0 @@ -# Data mapping - -Data mapping means referencing data from previous nodes. It doesn't include changing (transforming) data, just referencing it. - -You can map data in the following ways: - -* Using the expressions editor. Refer to [expressions](/code-examples/expressions/) for more information. -* By dragging and dropping data from the **INPUT** table into parameters. This generates the expression for you. - -## How to drag and drop data - -1. Run your workflow to load data. -2. Open the node where you need to map data. -3. Make sure the **INPUT** view is in **Table** layout. -4. Click and hold a table heading to map top level data, or a field in the table to map nested data. -5. Drag the item into the parameter field where you want to use the data. - -### Understand nested data - -Given the following data: - -```js -[ - { - "name": "First item", - "nested": { - "example-number-field": 1, - "example-string-field": "apples" - } - }, - { - "name": "Second item", - "nested": { - "example-number-field": 2, - "example-string-field": "oranges" - } - } -] -``` - -n8n displays it in table form like this: - -!["Screenshot of a table in the INPUT panel. It includes a top level field named "nested". This field contains nested data, which is indicated in bold."](/_images/data/data-mapping/nested-data.png) diff --git a/docs/data/data-mapping/data-item-linking/index.md b/docs/data/data-mapping/data-item-linking/index.md new file mode 100644 index 000000000..f6a97f600 --- /dev/null +++ b/docs/data/data-mapping/data-item-linking/index.md @@ -0,0 +1,18 @@ +# Data item linking + +An item is a single piece of data. Nodes receive one or more items, operate on them, and output new items. Each item links back to previous items. + +You need to be understand this behavior if you're: + +* Building a programmatic-style node that implements complex behaviors with its input and output data. Refer +* Using the Code node or expressions editor to access data from earlier items in the workflow. +* Using the Code node to implement complex behaviors with input and output data. + +This section provides: + +* A conceptual overview of [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts/). +* Information on [Item linking for node creators](/data/data-mapping/data-item-linking/item-linking-node-building/). +* Support for end users who need to [Work with the data path](/data/data-mapping/data-item-linking/item-linking-code-node/) to retrieve item data from previous nodes, and link items when using the Code node. +* Guidance on troubleshooting [Errors](/data/data-mapping/data-item-linking/item-linking-errors/). + + diff --git a/docs/data/data-mapping/data-item-linking/item-linking-code-node.md b/docs/data/data-mapping/data-item-linking/item-linking-code-node.md new file mode 100644 index 000000000..4139ea443 --- /dev/null +++ b/docs/data/data-mapping/data-item-linking/item-linking-code-node.md @@ -0,0 +1,4 @@ +# Item linking in the Code node +--8<-- "_snippets/data/data-mapping/item-linking-code-node.md" + + diff --git a/docs/data/data-mapping/data-item-linking/item-linking-concepts.md b/docs/data/data-mapping/data-item-linking/item-linking-concepts.md new file mode 100644 index 000000000..bf376de67 --- /dev/null +++ b/docs/data/data-mapping/data-item-linking/item-linking-concepts.md @@ -0,0 +1,30 @@ +# 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](/data/data-mapping/data-item-linking/item-linking-node-building/), for details on how to handle item linking when building a node. +* [Item linking in the Code node](/data/data-mapping/data-item-linking/item-linking-code-node/), to learn how to handle item linking in the Code node. +* [Item linking errors](/data/data-mapping/data-item-linking/item-linking-errors/), to understand the errors you may encounter in the editor UI. + +## n8n's automatic item linking + +If a node doesn't control how to link input items to output items, n8n 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), n8n can automatically add the correct linked item information. + * If the number of inputs and outputs is equal, n8n 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, n8n can't automatically link items. + +If n8n can't link items automatically, and the node doesn't handle the item linking, n8n displays an error. Refer to [Item linking errors](/data/data-mapping/data-item-linking/item-linking-errors/) for more information. + +## An item linking example + +![A diagram showing how you can track back from an item in your current node, to one in a previous node, even when items have been re-ordered](/_images/data/data-mapping/data-item-linking/item-linking.png) + +In this example, it's possible for n8n 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. + + diff --git a/docs/data/data-mapping/data-item-linking/item-linking-errors.md b/docs/data/data-mapping/data-item-linking/item-linking-errors.md new file mode 100644 index 000000000..02ca526d4 --- /dev/null +++ b/docs/data/data-mapping/data-item-linking/item-linking-errors.md @@ -0,0 +1,26 @@ +# Item linking errors + +n8n displays errors related to data mapping when there are problems tracing an item's linked parent items back through the workflow. + +## Errors when pinning data + +If you see this error message: + +> ERROR: '``' must be unpinned to execute + +Unpin the data in the named node, and execute the node to get fresh data. + +This error has two possible causes: + +* The number of inputs into the pinned node has changed since you pinned it. +* You've edited the pinned data and changed the number of items. + + +## Errors when using the Function node + +If you see this error message: + +> ERROR: Can't get data for expression under '``' field + +You need to supply item linking information yourself, because you have an item linking scenario that n8n can't automatically handle. Refer to [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts/) for a conceptual understanding of item linking, and [Manage item linking in the Function node](/data/data-mapping/data-item-linking/item-linking-code-node/) for detailed guidance on handling item linking. + diff --git a/docs/data/data-mapping/data-item-linking/item-linking-node-building.md b/docs/data/data-mapping/data-item-linking/item-linking-node-building.md new file mode 100644 index 000000000..96988d954 --- /dev/null +++ b/docs/data/data-mapping/data-item-linking/item-linking-node-building.md @@ -0,0 +1,3 @@ +# Item linking for node creators + +--8<-- "_snippets/data/data-mapping/item-linking-node-creators.md" diff --git a/docs/data/data-mapping/data-mapping-ui.md b/docs/data/data-mapping/data-mapping-ui.md new file mode 100644 index 000000000..880f38fca --- /dev/null +++ b/docs/data/data-mapping/data-mapping-ui.md @@ -0,0 +1,133 @@ +# Mapping in the UI + +Data mapping means referencing data from previous nodes. It doesn't include changing (transforming) data, just referencing it. + +You can map data in the following ways: + +* Using the expressions editor. +* By dragging and dropping data from the **INPUT** table or JSON into parameters. This generates the expression for you. + +## How to drag and drop data + +1. Run your workflow to load data. +2. Open the node where you need to map data. +3. You can map in both table and JSON view: + * In table view: click and hold a table heading to map top level data, or a field in the table to map nested data. + * In JSON view: click and hold an attribute. +4. Drag the item into the parameter field where you want to use the data. + +### Understand nested data + +Given the following data: + +```js +[ + { + "name": "First item", + "nested": { + "example-number-field": 1, + "example-string-field": "apples" + } + }, + { + "name": "Second item", + "nested": { + "example-number-field": 2, + "example-string-field": "oranges" + } + } +] +``` + +n8n displays it in table form like this: + +!["Screenshot of a table in the INPUT panel. It includes a top level field named "nested". This field contains nested data, which is indicated in bold."](/_images/data/data-mapping/nested-data.png) + +## Map data in the expressions editor + +These examples show how to access linked items in the expressions editor. Refer to [expressions](/code-examples/expressions/) for more information on expressions, including built in variables and methods. + +### Access the linked item in a previous node's output + +When you use this, n8n works back up the item linking chain, to find the parent item in the given node. + +```js +// Returns the linked item +{{$("").item}} +``` + +As a longer example, consider a scenario where a node earlier in the workflow has the following output data: + +```json +[ + { + "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", + } +] +``` + +To extract the name, use the following expression: + +```js +{{$("").item.json.name}} +``` + + +### Access the linked item in the current node's input + +In this case, the item linking is within the node: find the input item that the node links to an output item. + +```js +// Returns the linked item +{{$input.item}} +``` + +As a longer example, consider a scenario where the current node has the following input data: + +```json +[ + { + "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", + } +] +``` + +To extract the name, you'd normally use drag-and-drop [Data mapping](/data/data-mapping/), but you could also write the following expression: + +```js +{{$input.item.json.name}} +``` diff --git a/docs/data/data-mapping/index.md b/docs/data/data-mapping/index.md new file mode 100644 index 000000000..26f32fc20 --- /dev/null +++ b/docs/data/data-mapping/index.md @@ -0,0 +1,8 @@ +# Data mapping + +Data mapping means referencing data from previous nodes. + +This section contains guidance on: + +* Mapping data in most scenarios: [Data mapping](/data/data-mapping/data-mapping/) +* How to handle [item linking](/data/data-mapping/data-item-linking/) when using the Function node or building your own nodes. diff --git a/docs/data/data-structure.md b/docs/data/data-structure.md index 085bf2c4d..7baa2991d 100644 --- a/docs/data/data-structure.md +++ b/docs/data/data-structure.md @@ -9,16 +9,16 @@ In n8n, all data passed between nodes is an array of objects. It has the followi // Wrap each item in another object, with the key 'json' "json": { // Example data - "jsonKeyName": "keyValue", - "anotherJsonKey": { - "lowerLevelJsonKey": 1 + "apple": "beets", + "carrot": { + "dill": 1 } }, // For binary data: // Wrap each item in another object, with the key 'binary' "binary": { // Example data - "binaryKeyName": { + "apple-picture": { "data": "....", // Base64 encoded binary data (required) "mimeType": "image/png", // Best practice to set if possible (optional) "fileExtension": "png", // Best practice to set if possible (optional) @@ -30,11 +30,12 @@ In n8n, all data passed between nodes is an array of objects. It has the followi ``` !!! note "Skipping the 'json' key and array syntax" - From 0.166.0 onwards, when using the function node, n8n automatically adds the `json` key if it's missing. It also automatically wraps your items in an array (`[]`) if needed. This is only when using the Function node. When building your own nodes, you must still make sure the node returns data with the `json` key. + From 0.166.0 onwards, when using the Function node or Code node, n8n automatically adds the `json` key if it's missing. It also automatically wraps your items in an array (`[]`) if needed. This is only when using the Function or Code nodes. When building your own nodes, you must still make sure the node returns data with the `json` key. ## Data flow -Nodes do not only process one "item", they process multiple ones. +Nodes process multiple items. + For example, if the Trello node is set to `Create-Card` and it has an expression set for `Name` to be set depending on `name` property, it will create a card for each item, always choosing the `name-property-value` of the current one. This data would, for example, create two cards. One named `test1` the other one named `test2`: diff --git a/docs/data/index.md b/docs/data/index.md index 291106742..5cac59dfd 100644 --- a/docs/data/index.md +++ b/docs/data/index.md @@ -1,6 +1,6 @@ -# Overview +# Data -Data represents units of information that are collected by and transmitted through nodes. For "basic usage" it is not necessarily needed to understand how the data that gets passed from one node to another is structured. However, it becomes important if you want to: +Data is the information that n8n nodes receive and process. For basic usage of n8n you don't need to understand data structures and manipulation. However, it becomes important if you want to: - Create your own node - Write custom expressions @@ -10,4 +10,6 @@ This section covers: * [Data structure](/data/data-structure/) * [Transforming data](/data/transforming-data/) -* [Using code](/data/code/) \ No newline at end of file +* [Process data using code](/data/code/) +* [Pinning](/data/data-pinning/) and [editing](/data/data-editing/) data during workflow development. +* [Data mapping](/data/data-mapping/data-mapping/) and [Item linking](/data/data-mapping/data-item-linking/): how data items link to each other. diff --git a/docs/data/transforming-data.md b/docs/data/transforming-data.md index 33f7aabd7..968375dec 100644 --- a/docs/data/transforming-data.md +++ b/docs/data/transforming-data.md @@ -8,10 +8,10 @@ For example, the image below shows the output of an [HTTP Request](/integrations ![HTTP Request node output](/_images/data/transforming-data/HTTPRequest_output.png) -To transform this kind of structure into the n8n data structure you will have to use the Item Lists node. +To transform this kind of structure into the n8n data structure you can use the [Item Lists](/integrations/builtin/core-nodes/n8n-nodes-base.itemLists/) node. !!! note - If you're using the HTTP Request node, you should use the Split Into items option to transform the data. You don't have to use a Function node in that case. + If you're using the HTTP Request node, you should use the Split Into items option to transform the data. You don't have to use a Function node in that case. diff --git a/docs/editor-ui.md b/docs/editor-ui.md deleted file mode 100644 index 017e05d27..000000000 --- a/docs/editor-ui.md +++ /dev/null @@ -1,54 +0,0 @@ -# Editor UI - -The Editor UI is the web interface used to create [workflows](/workflows/). It is accessed through a web browser at a designated website address. - -![Editor](/_images/editor-ui/editor_ui.png) - -From the Editor UI, you can access all your workflows and credentials, as well as the n8n documentation and forum. - -The Editor UI sidebar menu contains the following sections and operations: - -## Admin Panel - -Available only for n8n Cloud, navigate to the Dashboard of your n8n Cloud instance. Here you can view your executions and workflows counts, manage and upgrade your instance, and access support. - -![Admin Panel](/_images/editor-ui/admin_panel.png) - -## Workflows - -This section includes the operations for creating and editing workflows. - -* **New**: Create a new workflow -* **Open**: Open the list of saved workflows -* **Save**: Save changes to the current workflow -* **Save As**: Save the current workflow under a new name -* **Rename**: Rename the current workflow -* **Delete**: Delete the current workflow -* **Download**: Download the current workflow as a JSON file -* **Import from URL**: Import a workflow from a URL -* **Import from File**: Import a workflow from a local file -* **Settings**: View and change the settings of the current workflow - -## Credentials - -This section includes the operations for creating [credentials](/integrations/). - -Credentials are private pieces of information issued by apps/services to authenticate you as a user and allow you to connect and share information between the app/service and the n8n node. - -* **New**: Create new credentials -* **Open**: Open the list of saved credentials - -## Executions - -This section includes information about your workflow executions, each completed run of a workflow. - -You can enabling logging of your failed, successful, and/or manually selected workflows using the Workflow > Settings page. - -## Help - -This section includes resources for using n8n and interacting with the community. - -* **Documentation**: Open the n8n documentation page -* **Forum**: Open the n8n community forum -* **Workflows**: Open the n8n public [workflows](https://n8n.io/workflows) page -* **About n8n**: View information about n8n (version, source code, license) diff --git a/docs/embed/configuration.md b/docs/embed/configuration.md index 041a431ff..eb5312687 100644 --- a/docs/embed/configuration.md +++ b/docs/embed/configuration.md @@ -96,7 +96,7 @@ It's possible to define external hooks that n8n executes whenever a specific ope | `credentials.update` | `[credentialData: ICredentialsDb]` | Called before existing credentials are saved. | | `frontend.settings` | `[frontendSettings: IN8nUISettings]` | Gets called on n8n startup. Allows you to, for example, overwrite frontend data like the displayed OAuth URL. | | `n8n.ready` | `[app: App]` | Called once n8n is ready. Can be used to, for example, register custom API endpoints. | -| `n8n.step` | | Called when an n8n process gets stopped. Allows you to save some process data. | +| `n8n.stop` | | Called when an n8n process gets stopped. Allows you to save some process data. | | `oauth1.authenticate` | `[oAuthOptions: clientOAuth1.Options, oauthRequestData: {oauth_callback: string}]` | Called before an OAuth1 authentication. Can be used to overwrite an OAuth callback URL. | | `oauth2.callback` | `[oAuth2Parameters: {clientId: string, clientSecret: string \| undefined, accessTokenUri: string, authorizationUri: string, redirectUri: string, scopes: string[]}]` | Called in an OAuth2 callback. Can be used to overwrite an OAuth callback URL. | | `workflow.activate` | `[workflowData: IWorkflowDb]` | Called before a workflow gets activated. Can be used to restrict the number of active workflows. | diff --git a/docs/embed/white-labelling.md b/docs/embed/white-labelling.md new file mode 100644 index 000000000..5c17a96b1 --- /dev/null +++ b/docs/embed/white-labelling.md @@ -0,0 +1,161 @@ +# White labelling + +White labelling n8n means customizing the frontend styling and assets to match your brand identity. The process involves changing two packages in n8n's source code [github.com/n8n-io/n8n](https://github.com/n8n-io/n8n){:target=_blank .external-link}: + +* [packages/design-system](https://github.com/n8n-io/n8n/tree/master/packages/design-system){:target=_blank .external-link}: n8n's [storybook](https://storybook.js.org/){:target=_blank .external-link} design system with CSS styles and Vue.js components +* [packages/editor-ui](https://github.com/n8n-io/n8n/tree/master/packages/editor-ui){:target=_blank .external-link}: n8n's [Vue.js](https://vuejs.org/){:target=_blank .external-link} frontend build with [Vite.js](https://vitejs.dev){:target=_blank .external-link} + +## Prerequisites + +You need the following installed on your development machine: + +--8<-- "_snippets/integrations/creating-nodes/prerequisites.md" + +Create a fork of [n8n's repository](https://github.com/n8n-io/n8n){:target=_blank .external-link} and clone your new repository. + +```shell +git clone https://github.com//n8n.git n8n +cd n8n +``` + +Install all dependencies, build and start n8n. + +```shell +npm install +npm run build +npm run start +``` + +Whenever you make changes you need to rebuild and restart n8n. While developing you can use `npm run dev` to automatically rebuild and restart n8n anytime you make code changes. + +## Theme colors + +To customize theme colors open [packages/design-system](https://github.com/n8n-io/n8n/tree/master/packages/design-system){:target=_blank .external-link} and start with: + +- [packages/design-system/src/css/_tokens.scss](https://github.com/n8n-io/n8n/blob/master/packages/design-system/src/css/_tokens.scss){:target=_blank .external-link} +- [packages/design-system/src/css/_tokens.dark.scss](https://github.com/n8n-io/n8n/blob/master/packages/design-system/src/css/_tokens.dark.scss){:target=_blank .external-link} + +At the top of `_tokens.scss` you will find `--color-primary` variables as HSL colors: + +```scss +@mixin theme { + --color-primary-h: 6.9; + --color-primary-s: 100%; + --color-primary-l: 67.6%; +``` + +In the following example the primary color changes to #0099ff. To convert to HSL you can use a [color converter tool](https://www.w3schools.com/colors/colors_converter.asp){:target=_blank .external-link}. + +```scss +@mixin theme { + --color-primary-h: 204; + --color-primary-s: 100%; + --color-primary-l: 50%; +``` + +![Example Theme Color Customization](/_images/embed/white-label/color-transition.gif) + +!!! note + Similar CSS variables in `_tokens.dark.scss` for dark mode are an upcoming feature that you can't toggle using n8n's UI yet. + +## Theme logos + +To change the editor’s logo assets look into [packages/editor-ui/public](https://github.com/n8n-io/n8n/tree/master/packages/editor-ui/public){:target=_blank .external-link} and replace: + +- favicon-16x16.png +- favicon-32x32.png +- favicon.ico +- n8n-logo.svg +- n8n-logo-collapsed.svg +- n8n-logo-expanded.svg + +Replace these logo assets. n8n uses them in Vue.js components, including: + +* [MainSidebar.vue](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/src/components/MainSidebar.vue){:target=_blank .external-link}: top/left logo in the main sidebar. +* [Logo.vue](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/src/components/Logo.vue): reused in other components. + +In the following example replace `n8n-logo-collapsed.svg` and `n8n-logo-expanded.svg` to update the main sidebar's logo assets. + +![Example Logo Main Sidebar](/_images/embed/white-label/logo-main-sidebar.png) + +If your logo assets require different sizing or placement you can customize SCSS styles at the bottom of [MainSidebar.vue](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/src/components/MainSidebar.vue){:target=_blank .external-link}. + +```scss +.logoItem { + display: flex; + justify-content: space-between; + height: $header-height; + line-height: $header-height; + margin: 0 !important; + border-radius: 0 !important; + border-bottom: var(--border-width-base) var(--border-style-base) var(--color-background-xlight); + cursor: default; + + &:hover, &:global(.is-active):hover { + background-color: initial !important; + } + + * { vertical-align: middle; } + .icon { + height: 18px; + position: relative; + left: 6px; + } + +} +``` + +## Text localization + +To change all text occurrences like `n8n` or `n8n.io` to your brand identity you can customize n8n's English internationalization file: [packages/editor-ui/src/plugins/i18n/locales/en.json](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/src/plugins/i18n/locales/en.json){:target=_blank .external-link}. + +n8n uses the [Vue I18n](https://kazupon.github.io/vue-i18n/){:target=_blank .external-link} internationalization plugin for Vue.js to translate the majority of UI texts. To search and replace text occurrences inside `en.json` you can use [Linked locale messages](https://kazupon.github.io/vue-i18n/guide/messages.html#linked-locale-messages){:target=_blank .external-link}. + +In the following example add the `_brand.name` translation key to white label n8n's [AboutModal.vue](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/src/components/AboutModal.vue){:target=_blank .external-link}. + +```js +{ + "_brand.name": "My Brand", + //replace n8n with link to _brand.name + "about.aboutN8n": "About @:_brand.name", + "about.n8nVersion": "@:_brand.name Version", +} +``` + +![Example About Modal Localization](/_images/embed/white-label/about-modal.png) + +### Window title + +To change n8n's window title to your brand name, edit the following: + +- [packages/editor-ui/index.html](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/index.html){:target=_blank .external-link} +- [packages/editor-ui/src/components/mixins/titleChange.ts](https://github.com/n8n-io/n8n/blob/master/packages/editor-ui/src/components/mixins/titleChange.ts){:target=_blank .external-link} + +The following example replaces all occurrences of `n8n` and `n8n.io` with `My Brand` in `index.html` and `titleChange.ts`. + +```html + + + + + My Brand - Workflow Automation + +``` + +```typescript +$titleSet(workflow: string, status: WorkflowTitleStatus) { + // replace n8n prefix + window.document.title = `My Brand - ${icon} ${workflow}`; +}, + +$titleReset() { + // replace n8n prefix + document.title = `My Brand - Workflow Automation`; +}, +``` + +![Example Window Title Localization](/_images/embed/white-label/window-title.png) + + + + diff --git a/docs/flow-logic/index.md b/docs/flow-logic/index.md index c0f5bae11..875c554ee 100644 --- a/docs/flow-logic/index.md +++ b/docs/flow-logic/index.md @@ -1,7 +1,7 @@ -# Overview +# Flow logic n8n allows you to represent complex logic in your workflows. * [Merging](/flow-logic/merging/) * [Looping](/flow-logic/looping/) -* [Error handling](/flow-logic/error-handling/) \ No newline at end of file +* [Error handling](/flow-logic/error-handling/) diff --git a/docs/hosting/configuration.md b/docs/hosting/configuration.md index 3069c69b2..caed6c784 100644 --- a/docs/hosting/configuration.md +++ b/docs/hosting/configuration.md @@ -172,9 +172,9 @@ You can define additional folders with an environment variable. export N8N_CUSTOM_EXTENSIONS="/home/jim/n8n/custom-nodes;/data/n8n/nodes" ``` -### Use built-in and external modules in Function-Nodes +### Use built-in and external modules in the Code node -For security reasons, the Function node restricts importing modules. It's possible to lift that restriction for built-in and external modules by setting the following environment variables: +For security reasons, the Code node restricts importing modules. It's possible to lift that restriction for built-in and external modules by setting the following environment variables: - `NODE_FUNCTION_ALLOW_BUILTIN`: For built-in modules - `NODE_FUNCTION_ALLOW_EXTERNAL`: For external modules sourced from n8n/node_modules directory. External module support is disabled when an environment variable isn't set. diff --git a/docs/hosting/databases/index.md b/docs/hosting/databases/index.md index e0b6d7061..b6f54cdcf 100644 --- a/docs/hosting/databases/index.md +++ b/docs/hosting/databases/index.md @@ -1,8 +1,8 @@ -# Overview +# Databases This section describes: * [n8n's database structure](/hosting/databases/structure/) * [Supported databases and settings](/hosting/databases/supported-databases-settings/) -For guidance on managing database size, refer to [Scaling | Execution data](/hosting/scaling/execution-data/). \ No newline at end of file +For guidance on managing database size, refer to [Scaling | Execution data](/hosting/scaling/execution-data/). diff --git a/docs/hosting/environment-variables.md b/docs/hosting/environment-variables.md index 6b1a21f33..1bf7f9fe5 100644 --- a/docs/hosting/environment-variables.md +++ b/docs/hosting/environment-variables.md @@ -160,8 +160,8 @@ Refer to [User management](/hosting/user-management/) for more information on se | :------- | :---- | :------- | :---------- | | `NODES_INCLUDE` | String | - | Specify which nodes to load. | | `NODES_EXCLUDE` | String | - | Specify which nodes not to load. | -| `NODE_FUNCTION_ALLOW_BUILTIN` | String | - | Permit users to import specific built-in modules in Function nodes. Use * to allow all. n8n disables importing modules by default. | -| `NODE_FUNCTION_ALLOW_EXTERNAL` | String | - | Permit users to import specific external modules (from `n8n/node_modules`) in Function nodes. n8n disables importing modules by default. | +| `NODE_FUNCTION_ALLOW_BUILTIN` | String | - | Permit users to import specific built-in modules in the Code node. Use * to allow all. n8n disables importing modules by default. | +| `NODE_FUNCTION_ALLOW_EXTERNAL` | String | - | Permit users to import specific external modules (from `n8n/node_modules`) in the Code node. n8n disables importing modules by default. | | `NODES_ERROR_TRIGGER_TYPE` | String | `n8n-nodes-base.errorTrigger` | Specify which Node Type to use as Error Trigger. | | `N8N_CUSTOM_EXTENSIONS` | String | - | Specify the path to additional directories containing your custom nodes. | @@ -176,6 +176,7 @@ Refer to [User management](/hosting/user-management/) for more information on se | `QUEUE_BULL_REDIS_PASSWORD` | String | - | The Redis password. | | `QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD` | Number | `10000` | The Redis timeout threshold (in seconds). | | `QUEUE_RECOVERY_INTERVAL` | Number | `60` | Interval (in seconds) for active polling to the queue to recover from Redis crashes. `0` disables recovery. May increase Redis traffic significantly. | +| `QUEUE_WORKER_TIMEOUT` | Number | `30` | How long should n8n wait (seconds) for running executions before exiting worker process on shutdown. | | `QUEUE_HEALTH_CHECK_ACTIVE` | Boolean | `false` | Whether to enable health checks (true) or disable (false). | | `QUEUE_HEALTH_CHECK_PORT` | Number | - | The port to serve health checks on. | diff --git a/docs/hosting/installation/cloud.md b/docs/hosting/installation/cloud.md index d6c300763..fced8e283 100644 --- a/docs/hosting/installation/cloud.md +++ b/docs/hosting/installation/cloud.md @@ -1,18 +1,26 @@ # n8n Cloud -n8n Cloud is our hosted solution. In addition to all the features of n8n, it provides added benefits such as: +n8n Cloud is n8n's hosted solution. In addition to all the features of n8n, it provides added benefits such as: - No technical set up or maintenance for your n8n instance - 24/7 uptime monitoring - Managed OAuth for authentication -- Easy upgrades to the newest n8n versions +- One-click upgrades to the newest n8n versions -[Sign up for n8n Cloud](https://www.n8n.cloud/) +[Sign up for n8n Cloud](https://www.n8n.cloud/){:target=_blank .external-link} -!!! note "Cloud IP addresses" - Currently it is `20.79.72.105`, however this is subject to change. The NAT addresses are `20.79.227.226` and `20.79.72.36`, but this is also subject to change. - Recommended practice is to whitelist `20.79.72.0/24`, but if more strict measures are needed, at minimum `20.79.72.105`, `20.79.72.36`, and `20.79.227.226` must be whitelisted. - - -!!! warning "Russia and Belarus" +!!! note "Russia and Belarus" n8n Cloud is not available in Russia and Belarus. Refer to our blog post [Update on n8n cloud accounts in Russia and Belarus](https://n8n.io/blog/update-on-n8n-cloud-accounts-in-russia-and-belarus/) for more information. + + +## Cloud IP addresses + +!!! warning "Cloud IP addresses change without warning" + n8n can't guarantee static source IPs, as Cloud operates in a dynamic cloud provider environment and scales its infrastructure to meet demand. You should use strong authentication and secure transport protocols when connecting into and out of n8n. + +Outbound traffic may currently appear to originate from any of: + +* 20.79.227.226 +* 20.79.72.36 +* 20.218.202.73 + diff --git a/docs/hosting/installation/index.md b/docs/hosting/installation/index.md index 4f61ba027..ff2a8e5d9 100644 --- a/docs/hosting/installation/index.md +++ b/docs/hosting/installation/index.md @@ -1,8 +1,8 @@ -# Overview +# Installation Installation guides for n8n: * [Desktop app](/hosting/installation/desktop-app/) * [npm](/hosting/installation/npm/) * [Docker](/hosting/installation/docker/) -* [Cloud](/hosting/installation/cloud/) \ No newline at end of file +* [Cloud](/hosting/installation/cloud/) diff --git a/docs/hosting/scaling/queue-mode.md b/docs/hosting/scaling/queue-mode.md index b08cb570a..b75bbe211 100644 --- a/docs/hosting/scaling/queue-mode.md +++ b/docs/hosting/scaling/queue-mode.md @@ -69,6 +69,7 @@ You can also set the following optional configurations: | `queue.bull.redis.db:0` | `QUEUE_BULL_REDIS_DB` | The default value is `0`. If you change this value, update the configuration. | | `queue.bull.redis.timeoutThreshold:10000ms` | `QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD` | Tells n8n how long it should wait if Redis is unavailable before exiting. The default value is `10000ms`. | | `queue.bull.queueRecoveryInterval:60` | `QUEUE_RECOVERY_INTERVAL` | Adds an active watchdog to n8n that checks Redis for finished executions. This is used to recover when n8n's main process loses connection temporarily to Redis and is not notified about finished jobs. The default value is `60` seconds. | +| `queue.bull.gracefulShutdownTimeout:30` | `QUEUE_WORKER_TIMEOUT` | A graceful shutdown timeout for workers to finish executing jobs before terminating the process. The default value is `30` seconds. | Now you can start your n8n instance and it will connect to your Redis instance. diff --git a/docs/hosting/server-setups/aws.md b/docs/hosting/server-setups/aws.md new file mode 100644 index 000000000..dfc6d0e7f --- /dev/null +++ b/docs/hosting/server-setups/aws.md @@ -0,0 +1,165 @@ +# Hosting n8n on Amazon Web Services + +This hosting guide shows you how to self-host n8n with Amazon Web Services (AWS). It uses n8n with Postgres as a database backend using Kubernetes to manage the necessary resources and reverse proxy. + +## Hosting options + +AWS offers several ways suitable for hosting n8n, including EC2 (virtual machines), and EKS (containers running with Kubernetes). + +This guide uses [EKS](https://aws.amazon.com/eks/){:target=_blank .external-link} as the hosting option. Using Kubernetes requires some additional complexity and configuration, but is the best method for scaling n8n as demand changes. + +## Prerequisites + +The steps in this guide use a mix of the AWS UI and [the eksctl CLI tool for EKS](https://eksctl.io){:target=_blank .external-link}. + +While not mentioned in the documentation for eksctl, you also need to [install the AWS CLI tool](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html){:target=_blank .external-link}, and [configure authentication of the tool](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html){:target=_blank .external-link}. + +## Create a cluster + +Use the eksctl tool to create a cluster specifying a name and a region with the following command: + +```shell +eksctl create cluster --name n8n --region +``` + +This can take a while to create the cluster. + + +Once the cluster is created, eksctl automatically sets the kubectl context to the cluster. + +## Clone configuration repository + +Kubernetes and n8n require a series of configuration files. You can clone these from [this repository](https://github.com/n8n-io/n8n-kubernetes-hosting/tree/aws){:target=_blank .external-link}. The following steps tell you what each file does, and what settings you need to change. + +Clone the repository with the following command: + +```shell +git clone https://github.com/n8n-io/n8n-kubernetes-hosting.git -b aws +``` + +And change directory to the root of the repository you cloned: + +```shell +cd n8n-kubernetes-hosting +``` + +## Configure Postgres + +For larger scale n8n deployments, Postgres provides a more robust database backend than SQLite. + +### Configure volume for persistent storage + +To maintain data between pod restarts, the Postgres deployment needs a persistent volume. The default AWS storage class, [gp2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/general-purpose.html#EBSVolumeTypes_gp2){:target=_blank .external-link}, is suitable for this purpose. This is defined in the `postgres-claaim0-persistentvolumeclaim.yaml` manifest. + +```yaml +… +spec: + storageClassName: gp2 + accessModes: + - ReadWriteOnce +… +``` + +### Environment variables + +Postgres needs some environment variables set to pass to the application running in the containers. + +The example `postgres-secret.yaml` file contains placeholders you need to replace with values of your own for user details and the database to use. + +The `postgres-deployment.yaml` manifest then uses the values from this manifest file to send to the application pods. + +## Configure n8n + +### Create a volume for file storage + +While not essential for running n8n, using persistent volumes helps maintain files uploaded while using n8n and if you want to persist [manual n8n encryption keys](https://docs.n8n.io/hosting/configuration/#encryption-key) between restarts, which saves a file containing the key into file storage during startup. + +The `n8n-claim0-persistentvolumeclaim.yaml` manifest creates this, and the n8n Deployment mounts that claim in the `volumes` section of the `n8n-deployment.yaml` manifest. + +```yaml +… +volumes: + - name: n8n-claim0 + persistentVolumeClaim: + claimName: n8n-claim0 +… +``` + +### Pod resources + +[Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/){:target=_blank .external-link} lets you specify the minimum resources application containers need and the limits they can run to. The example YAML files cloned above contain the following in the `resources` section of the `n8n-deployment.yaml` file: + +```yaml +… +resources: + requests: + memory: "250Mi" + limits: + memory: "500Mi" +… +``` + +This defines a minimum of 250mb per container, a maximum of 500mb, and lets Kubernetes handle CPU. You can change these values to match your own needs. As a guide, here are the resources values for the n8n cloud offerings: + +- **Start**: 320mb RAM, 10 millicore CPU burstable +- **Pro**: 640mb RAM, 20 millicore CPU burstable +- **Power**: 1280mb RAM, 80 millicore CPU burstable + +### Environment variables + +n8n needs some environment variables set to pass to the application running in the containers. + +The example `n8n-secret.yaml` file contains placeholders you need to replace with values of your own for authentication details. + +## Deployments + +The two deployment manifests (`n8n-deployment.yaml` and `postgres-deployment.yaml`) define the n8n and Postgres applications to Kubernetes. + +The manifests define the following: + +- Send the environment variables defined to each application pod +- Define the container image to use +- Set resource consumption limits +- The `volumes` defined earlier and `volumeMounts` to define the path in the container to mount volumes. +- Scaling and restart policies. The example manifests define one instance of each pod. You should change this to meet your needs. + +## Services + +The two service manifests (`postgres-service.yaml` and `n8n-service.yaml`) expose the services to the outside world using the Kubernetes load balancer using ports 5432 and 5678 respectively by default. + +## Send to Kubernetes cluster + +Send all the manifests to the cluster by running the following command in the `n8n-kubernetes-hosting` directory: + +```shell +kubectl apply -f . +``` + +!!! note "Namespace error" + You may see an error message about not finding an "n8n" namespace as that resources isn't ready yet. You can run the same command again, or apply the namespace manifest first with the following command: + + ```shell + kubectl apply -f namespace.yaml + ``` + +## Set up DNS + +n8n typically operates on a subdomain. Create a DNS record with your provider for the subdomain and point it to a static address of the instance. + +To find the address of the n8n service running on the instance: + +1. Open the **Clusters** section of the **Amazon Elastic Kubernetes Service** page in the AWS console. +2. Select the name of the cluster to open its configuration page. +3. Select the **Resources** tab, then **Service and networking** > **Services**. +4. Select the **n8n** service and copy the **Load balancer URLs** value. Use this value suffixed with the n8n service port (5678) for DNS. + +!!! note "Use HTTP" + This guide uses HTTP connections for the services it defines, for example in `n8n-deployment.yaml`. However, if you click the **Load balancer URLs** value, EKS takes you to an "HTTPS" URL which results in an error. To solve this, when you open the n8n subdomain, make sure to use HTTP. + +## Delete resources + +If you need to delete the setup, you can remove the resources created by the manifests with the following command: + +```shell +kubectl delete -f . +``` diff --git a/docs/hosting/server-setups/google-cloud.md b/docs/hosting/server-setups/google-cloud.md new file mode 100644 index 000000000..5a6efd41d --- /dev/null +++ b/docs/hosting/server-setups/google-cloud.md @@ -0,0 +1,172 @@ +# Hosting n8n on Google Cloud + +This hosting guide shows you how to self-host n8n on Google Cloud (GCP). It uses n8n with Postgres as a database backend using Kubernetes to manage the necessary resources and reverse proxy. + +## Prerequisites + +- The [gcloud command line tool](https://cloud.google.com/sdk/gcloud/){:target="_blank" .external-link} +- The [gke-gcloud-auth-plugin](https://cloud.google.com/blog/products/containers-kubernetes/kubectl-auth-changes-in-gke){:target="_blank" .external-link} (install the gcloud CLI first) + +## Hosting options + +Google Cloud offers several options suitable for hosting n8n, including Cloud Run (optimized for running containers), Compute Engine (VMs), and Kubernetes Engine (containers running with Kubernetes). + +This guide uses the Google Kubernetes Engine (GKE) as the hosting option. Using Kubernetes requires some additional complexity and configuration, but is the best method for scaling n8n as demand changes. + +Most of the steps in this guide use the Google Cloud UI, but you can also use the [gcloud command line tool](https://cloud.google.com/sdk/gcloud/){:target="_blank" .external-link} instead to undertake all the steps. + +## Create project + +GCP encourages you to create projects to logically organize resources and configuration. Create a new project for your n8n deployment from your Google Cloud Console: select the project dropdown menu and then the **NEW PROJECT** button. Then select the newly created project. As you follow the other steps in this guide, make sure you have the correct project selected. + +## Enable the Kubernetes Engine API + +GKE isn't enabled by default. Search for "Kubernetes" in the top search bar and select "Kubernetes Engine" from the results. + +Select **ENABLE** to enable the Kubernetes Engine API for this project. + +## Create a cluster + +From the [GKE service page](https://console.cloud.google.com/kubernetes/list/overview){:target=_blank .external-link}, select **Clusters** > **CREATE**. Make sure you select the "Standard" cluster option, n8n doesn't work with an "Autopilot" cluster. You can leave the cluster configuration on defaults unless there's anything specifically you need to change, such as location. + +## Set Kubectl context + +The rest of the steps in this guide require you to set the GCP instance as the Kubectl context. You can find the connection details for a cluster instance by opening its details page and selecting **CONNECT**. The displayed code snippet shows a connection string for the gcloud CLI tool. Paste and run the code snippet in the gcloud CLI to change your local Kubernetes settings to use the new gcloud cluster. + +## Clone configuration repository + +Kubernetes and n8n require a series of configuration files. You can clone these from [this repository](https://github.com/n8n-io/n8n-kubernetes-hosting/tree/gcp){:target=_blank .external-link} locally. The following steps explain the file configuration and how to add your information. + +Clone the repository with the following command: + +```shell +git clone https://github.com/n8n-io/n8n-kubernetes-hosting.git -b gcp +``` + +And change directory to the root of the repository you cloned: + +```shell +cd n8n-kubernetes-hosting +``` + +## Configure Postgres + +For larger scale n8n deployments, Postgres provides a more robust database backend than SQLite. + +### Create a volume for persistent storage + +To maintain data between pod restarts, the Postgres deployment needs a persistent volume. Running Postgres on GCP requires a specific Kubernetes Storage Class. You can read [this guide](https://cloud.google.com/architecture/deploying-highly-available-postgresql-with-gke){:target="_blank" .external-link} for specifics, but the `storage.yaml` manifest creates it for you. You may want to change the regions to create the storage in under the `allowedTopologies` > `matchedLabelExpressions` > `values` key. By default, they're set to "us-central". + +```yaml +… +allowedTopologies: + - matchLabelExpressions: + - key: failure-domain.beta.kubernetes.io/zone + values: + - us-central1-b + - us-central1-c +``` + +### Postgres environment variables + +Postgres needs some environment variables set to pass to the application running in the containers. + +The example `postgres-secret.yaml` file contains placeholders you need to replace with your own values. Postgres will use these details when creating the database.. + +The `postgres-deployment.yaml` manifest then uses the values from this manifest file to send to the application pods. + +## Configure n8n + +### Create a volume for file storage + +While not essential for running n8n, using persistent volumes is required for: + +* Using nodes that interact with files, such as the binary data node. +* If you want too persist [manual n8n encryption keys](https://docs.n8n.io/hosting/configuration/#encryption-key) between restarts. This saves a file containing the key into file storage during startup. + +The `n8n-claim0-persistentvolumeclaim.yaml` manifest creates this, and the n8n Deployment mounts that claim in the `volumes` section of the `n8n-deployment.yaml` manifest. + +```yaml +… +volumes: + - name: n8n-claim0 + persistentVolumeClaim: + claimName: n8n-claim0 +… +``` + +### Pod resources + +[Kubernetes lets you](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) optionally specify the minimum resources application containers need and the limits they can run to. The example YAML files cloned above contain the following in the `resources` section of the `n8n-deployment.yaml` and `postgres-deployment.yaml` files: + +```yaml +… +resources: + requests: + memory: "250Mi" + limits: + memory: "500Mi" +… +``` + +This defines a minimum of 250mb per container, a maximum of 500mb, and lets Kubernetes handle CPU. You can change these values to match your own needs. As a guide, here are the resources values for the n8n cloud offerings: + +- **Start**: 320mb RAM, 10 millicore CPU burstable +- **Pro**: 640mb RAM, 20 millicore CPU burstable +- **Power**: 1280mb RAM, 80 millicore CPU burstable + + +### Environment variables + +n8n needs some environment variables set to pass to the application running in the containers. + +The example `n8n-secret.yaml` file contains placeholders you need to replace with values of your own for authentication details. + +Refer to [Environment variables](/hosting/environment-variables/) for n8n environment variables details. + +## Deployments + +The two deployment manifests (`n8n-deployment.yaml` and `postgres-deployment.yaml`) define the n8n and Postgres applications to Kubernetes. + +The manifests define the following: + +- Send the environment variables defined to each application pod +- Define the container image to use +- Set resource consumption limits with the `resources` object +- The `volumes` defined earlier and `volumeMounts` to define the path in the container to mount volumes. +- Scaling and restart policies. The example manifests define one instance of each pod. You should change this to meet your needs. + +## Services + +The two service manifests (`postgres-service.yaml` and `n8n-service.yaml`) expose the services to the outside world using the Kubernetes load balancer using ports 5432 and 5678 respectively. + +## Send to Kubernetes cluster + +Send all the manifests to the cluster with the following command: + +```shell +kubectl apply -f . +``` + +!!! note "Namespace error" + You may see an error message about not finding an "n8n" namespace as that resources isn't ready yet. You can run the same command again, or apply the namespace manifest first with the following command: + + ```shell + kubectl apply -f namespace.yaml + ``` + +## Set up DNS + +n8n typically operates on a subdomain. Create a DNS record with your provider for the subdomain and point it to the IP address of the n8n service. Find the IP address of the n8n service from the **Services & Ingress** menu item of the cluster you want to use under the **Endpoints** column. + +!!! note "GKE and IP addresses" + + [Read this GKE tutorial](https://cloud.google.com/kubernetes-engine/docs/tutorials/configuring-domain-name-static-ip#configuring_your_domain_name_records){:target="_blank" .external-link} for more details on how reserved IP addresses work with GKE and Kubernetes resources. + +## Delete resources + +Remove the resources created by the manifests with the following command: + +```shell +kubectl delete -f . +``` diff --git a/docs/hosting/server-setups/index.md b/docs/hosting/server-setups/index.md index d10b00a95..63d12664e 100644 --- a/docs/hosting/server-setups/index.md +++ b/docs/hosting/server-setups/index.md @@ -4,6 +4,9 @@ Guides to self-hosting n8n with: * [Docker Compose](/hosting/server-setups/docker-compose/) * [Caddy](/hosting/server-setups/caddy/) +* [Digital Ocean](/hosting/server-setups/digital-ocean/) (using Caddy and Docker Compose) +* [AWS](/hosting/server-setups/aws/) +* [Google Cloud Platform](/hosting/server-setups/google-cloud/) !!! warning "Secure your n8n instance" diff --git a/docs/hosting/user-management.md b/docs/hosting/user-management.md index 18077e0d8..d0670c7cc 100644 --- a/docs/hosting/user-management.md +++ b/docs/hosting/user-management.md @@ -1,13 +1,18 @@ # User management +!!! info "Feature availability" + + * Available on self-hosted and selected Cloud plans. Refer to [Cloud Pricing](https://n8n.io/pricing/){:target=_blank .external-link} for more information. + * Not available on Desktop. + * Cloud users don't need to configure SMTP, and can't configure email templates. + + User management in n8n allows you to invite people to work in your n8n instance. It includes: * Login and password management * Adding and removing users * Two account types: owner and member -User management is available for self-hosted n8n. It isn't currently available for Cloud or Desktop. - !!! note "Privacy" The user management feature doesn't send personal information, such as email or username, to n8n. @@ -16,11 +21,12 @@ User management is available for self-hosted n8n. It isn't currently available f There are two account types, owner and member. The account type affects the user permissions and access. -* Owner: this is the account that set up user management. There is one owner account for each n8n instance. You can't transfer ownership. +* Owner: this is the account that set up user management. There's one owner account for each n8n instance. You can't transfer ownership. The owner can: * Add and remove users * See all workflows * Delete tags + * See all credentials (but not the sensitive information) * Members: these are normal n8n users. Members can: * See all workflow tags, create new tags, and assign tags to their workflows. Members can't delete tags. @@ -31,7 +37,7 @@ There are two account types, owner and member. The account type affects the user We recommend that owners create a member-level account for themselves. Owners can see all workflows, but there is no way to see who created a particular workflow, so there is a risk of overriding other people's work if you build and edit workflows as an owner. -## Setup +## Set up on self-hosted n8n There are three stages to set up user management in n8n: @@ -91,9 +97,33 @@ You can now invite other people to your n8n instance. 5. Enter the new user's email address. 6. Click **Invite user**. n8n sends an email with a link for the new user to join. +## Set up on n8n Cloud + +!!! warning "Irreversible upgrade" + Once you upgrade your Cloud instance to an n8n version with user management, you can't downgrade your version. + +### Step one: in-app setup + +When you set up user management for the first time, you create an owner account. + +1. Open n8n. The app displays a signup screen. +2. Enter your details. Your password must be at least eight characters, including at least one number and one capital letter. +3. Click **Next**. n8n logs you in with your new owner account. + +### Step two: invite users + +You can now invite other people to your n8n instance. + +1. Sign in with your owner account. +2. Click your user icon > **Settings**. n8n opens your **Personal settings** page. +3. Click **Users** to go to the **Users** page. +4. Click **Invite**. +5. Enter the new user's email address. +6. Click **Invite user**. n8n sends an email with a link for the new user to join. + ## Manage users -The **Users** page shows all users, including ones with pending invitations. +The **Settings** > **Users** page shows all users, including ones with pending invitations. ### Delete a user @@ -110,7 +140,7 @@ Click the menu icon by the user, then click **Resend invite**. You don't have to use n8n's user management feature. You can: * Leave it enabled, but choose to skip the setup step. You can use n8n as normal. If you want to set up user management later, go to **Settings** > **Users**. -* Disable the feature completely using the `N8N_USER_MANAGEMENT_DISABLED` environment variable. Setting this environment variable to `true` completely hides the feature in your n8n instance. You can't use this setting if you have already set up an owner account. +* Self-hosted only: Disable the feature completely using the `N8N_USER_MANAGEMENT_DISABLED` environment variable. Setting this environment variable to `true` completely hides the feature in your n8n instance. You can't use this setting if you have already set up an owner account. ## Best practices diff --git a/docs/integrations/builtin/app-nodes/index.md b/docs/integrations/builtin/app-nodes/index.md index 0053d84d9..470105543 100644 --- a/docs/integrations/builtin/app-nodes/index.md +++ b/docs/integrations/builtin/app-nodes/index.md @@ -1,3 +1,3 @@ -# Overview +# App nodes library -This section provides information about n8n's app nodes. \ No newline at end of file +This section provides information about n8n's app nodes. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.adalo.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.adalo.md new file mode 100644 index 000000000..8c6d801b8 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.adalo.md @@ -0,0 +1,19 @@ +# Adalo + +[Adalo](https://www.adalo.com/){:target=_blank .external-link} is a low code app builder. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/adalo/). + +## Operations + +* Collection + * Create + * Delete + * Get + * Get Many + * Update + +## Related resources + +Refer to [Adalo's documentation](https://help.adalo.com/){:target=_blank .external-link} for more information on using Adalo. Their [External Collections with APIs](https://help.adalo.com/integrations/external-collections-with-apis){:target=_blank .external-link} page gives more detail about what you can do with Adalo collections. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.awsCertificateManager.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.awsCertificateManager.md new file mode 100644 index 000000000..0ebc79317 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.awsCertificateManager.md @@ -0,0 +1,21 @@ +# AWS Certificate Manager + +[AWS Certificate Manager](https://aws.amazon.com/certificate-manager/){:target=_blank .external-link} is a service that lets you provision, manage, and deploy public and private Secure Sockets Layer/Transport Layer Security (SSL/TLS) certificates for use with AWS services and your internal connected resources. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/aws/). + +## Operations + +* Certificate + * Delete + * Get + * Get Many + * Get Metadata + * Renew + +## Related resources + +Refer to [AWS Certificate Manager's documentation](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html){:target=_blank .external-link} for more information on this service. + +View [example workflows and related content](https://n8n.io/integrations/aws-certificate-manager/){:target=_blank .external-link} on n8n's website. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.awsElb.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.awsElb.md new file mode 100644 index 000000000..c835a76b1 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.awsElb.md @@ -0,0 +1,26 @@ +# AWS Elastic Load Balancing + +[AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/){:target=_blank .external-link} (ELB) automatically distributes incoming application traffic across multiple targets and virtual appliances in one or more Availability Zones (AZs). + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/aws/). + +## Operations + +* Listener Certificate + * Add + * Get Many + * Remove +* Load Balancer + * Create + * Delete + * Get + * Get Many + +This node supports creating and managing application and network load balancers. It doesn't currently support gateway load balancers. + +## Related resources + +Refer to [AWS ELB's documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/userguide/what-is-load-balancing.html){:target=_blank .external-link} for more information on this service. + +View [example workflows and related content](https://n8n.io/integrations/aws-elb/){:target=_blank .external-link} on n8n's website. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.citrixAdc.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.citrixAdc.md new file mode 100644 index 000000000..0b8254ea5 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.citrixAdc.md @@ -0,0 +1,22 @@ +# Citrix ADC + +[Citrix ADC](https://www.citrix.com/en-gb/products/citrix-adc/){:target=_blank .external-link} is an application delivery and load balancing solution for monolithic and microservices-based applications. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/citrixAdc/). + +## Operations + +* Certificate + * Create + * Install +* File + * Delete + * Download + * Upload + +## Related resources + +Refer to [Citrix ADC's documentation](https://docs.citrix.com/en-us/citrix-adc/current-release/){:target=_blank .external-link} for more information about the service. + +View [example workflows and related content](https://n8n.io/integrations/citrix-adc/){:target=_blank .external-link} on n8n's website. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.cloudflare.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.cloudflare.md new file mode 100644 index 000000000..604d25436 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.cloudflare.md @@ -0,0 +1,20 @@ +# Cloudflare + +[Cloudflare](https://www.cloudflare.com/){:target=_blank .external-link} provides a range of services to manage and protect your websites. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/cloudflare/). + +## Operations + +* Zone Certificate + * Delete + * Get + * Get Many + * Upload + +## Related resources + +Refer to [Cloudflare's API documentation on zone-level authentication](https://api.cloudflare.com/#zone-level-authenticated-origin-pulls-properties){:target=_blank .external-link} for more information on this service. + +View [example workflows and related content](https://n8n.io/integrations/cloudflare/){:target=_blank .external-link} on n8n's website. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.gmail.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.gmail.md index cbae04020..8621e493f 100644 --- a/docs/integrations/builtin/app-nodes/n8n-nodes-base.gmail.md +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.gmail.md @@ -1,113 +1,49 @@ # Gmail -[Gmail](https://www.gmail.com) is an email service developed by Google. Users can access Gmail on the web and using third-party programs that synchronize email content through POP or IMAP protocols. +[Gmail](https://www.gmail.com){:target=_blank .external-link} is an email service developed by Google. !!! note "Credentials" You can find authentication information for this node [here](/integrations/builtin/credentials/google/). -## Basic Operations +## Operations * Draft - * Create a new email draft - * Delete a draft - * Get a draft - * Get all drafts + * Create + * Delete + * Get + * Get Many * Label - * Create a new label - * Delete a label - * Get a label - * Get all labels + * Create + * Delete + * Get + * Get Many * Message - * Send an email - * Delete a message - * Get a message - * Get all messages - * Reply to an email -* Message Label - * Add a label to a message - * Remove a label from a message + * Add Label + * Delete + * Get + * Get Many + * Mark as Read + * Mark as Unread + * Remove Label + * Reply + * Send +* Thread + * Add Label + * Delete + * Get + * Get Many + * Remove Label + * reply + * Trash + * Untrash -## Example Usage +## Related resources -This workflow allows you to get all messages with a certain label, remove the label from the messages, and add a new label to the messages. You can also find the [workflow](https://n8n.io/workflows/621) on n8n.io. This example usage workflow would use the following nodes. -- [Start](/integrations/builtin/core-nodes/n8n-nodes-base.start/) -- [Gmail]() - -The final workflow should look like the following image. - -![A workflow with the Gmail node](/_images/integrations/builtin/app-nodes/gmail/workflow.png) - -### 1. Start node - -The start node exists by default when you create a new workflow. - -### 2. Gmail node (getAll: message) - -This node will return ten messages with the label `n8n` from Gmail. If you want to return all the messages toggle ***Return All*** to `true`. - -1. First of all, you'll have to enter credentials for the Gmail node. You can find out how to do that [here](/integrations/builtin/credentials/google/). -2. Select 'Message' from the ***Resource*** dropdown list. -3. Select 'Get All' from the ***Operation*** dropdown list. -4. Click on the ***Add Field*** button and select 'Format' from the dropdown list. -5. Select 'Full' from ***Format*** dropdown menu. This option will return the full email message data with the body content parsed in the payload field. -6. Click on the ***Add Field*** button and select 'Label IDs' from the dropdown list. -7. Select the label from the ***Label IDs*** dropdown list. -8. Click on ***Execute Node*** to run the node. - -In the screenshot below, you will notice that the node returns ten email messages with the label `n8n`. - -![Using the Gmail node to get all messages with a particular label](/_images/integrations/builtin/app-nodes/gmail/gmail_node.png) - - - -### 3. Gmail1 node (remove: messageLabel) - -This node will remove the label `n8n` from all the messages that you received in the previous node. If you want to remove a different label, select that label instead. - -1. Select the credentials that you entered in the previous Gmail node. -2. Select 'Message Label' from the ***Resource*** dropdown list. -3. Select 'Remove' from the ***Operation*** dropdown list. -4. Click on the gears icon next to the ***Message ID*** field and click on ***Add Expression***. -5. Select the following in the ***Variable Selector*** section: Nodes > Gmail > Output Data > JSON > id. You can also add the following expression: `{{$node["Gmail"].json["id"]}}`. -6. Select the label from the ***Label IDs*** dropdown list. -7. Click on ***Execute Node*** to run the node. - -In the screenshot below, you will notice that the node removes the `n8n` label from the messages that we received from the previous node. - -![Using the Gmail node to remove a label from the messages](/_images/integrations/builtin/app-nodes/gmail/gmail1_node.png) - - -### 4. Gmail2 node (add: messageLabel) - -This node will add a new label `nodemation` to the messages that we received from the Gmail node. If you want to add a different label, select that label instead. - -1. Select the credentials that you entered in the previous Gmail node. -2. Select 'Message Label' from the ***Resource*** dropdown list. -3. Click on the gears icon next to the ***Message ID*** field and click on ***Add Expression***. -4. Select the following in the ***Variable Selector*** section: Nodes > Gmail > Output Data > JSON > id. You can also add the following expression: `{{$node["Gmail"].json["id"]}}`. -5. Select the label from the ***Label IDs*** dropdown list. -6. Click on ***Execute Node*** to run the node. - -In the screenshot below, you will notice that the node adds a new label `nodemation` to the messages that we received from the Gmail node. - -![Using the Gmail node to add a label to the messages](/_images/integrations/builtin/app-nodes/gmail/gmail2_node.png) - -## FAQs - -### How to return all the messages with a particular label? - -To return all the messages with a particular label, follow the steps mentioned below. - -1. Select 'Message' from the ***Resource*** dropdown list. -2. Select 'Get All' from the ***Operation*** dropdown list. -3. If you want to all return all the messages with a particular, toggle ***Return All*** to `true`. -4. Click on ***Add Field*** and select 'Query'. -5. Enter `label:LABEL_NAME` in the ***Query*** field. Replace `LABEL_NAME` with your label name. -6. Click on ***Execute Node*** to run the node. - -Refer to [Search operators you can use with Gmail](https://support.google.com/mail/answer/7190?hl=en) to learn more about filtering your search results. +Refer to Google's [Gmail API documentation](https://developers.google.com/gmail/api) for detailed information about the API that this node integrates with. +n8n provides a trigger node for Gmail. You can find the trigger node docs [here](/integrations/builtin/trigger-nodes/gmailTrigger/). +View [example workflows and related content](https://n8n.io/integrations/356-gmail/){:target=_blank .external-link} on our website. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudStorage.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudStorage.md new file mode 100644 index 000000000..2d81d5e2f --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudStorage.md @@ -0,0 +1,25 @@ +# Google Cloud Storage + +[Google Cloud Storage](https://cloud.google.com/storage){:target=_blank .external-link} offers object storage for data, with flexible capacity and retrieval. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/google/). + +## Operations + +* Bucket + * Create + * Delete + * Get + * Get Many + * Update +* Object + * Create + * Delete + * Get + * Get Many + * Update + +## Related resources + +Refer to Google's [Cloud Storage API documentation](https://cloud.google.com/storage/docs/apis){:target=_blank .external-link} for detailed information about the API that this node integrates with. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md index 95e8994df..8bb25daea 100644 --- a/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.slack.md @@ -46,6 +46,7 @@ * Get all stars of autenticated user. * User * Get information about a user + * Get a list of users * Get online status of a user * User Group * Create a user group diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.venafiTlsProtectCloud.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.venafiTlsProtectCloud.md new file mode 100644 index 000000000..5da667502 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.venafiTlsProtectCloud.md @@ -0,0 +1,32 @@ +# Venafi TLS Protect Cloud + +[Venafi](https://www.venafi.com/){:target=_blank .external-link} is a cybersecurity company providing services for machine identity management. They offer solutions to manage and protect identities for a wide range of machine types, delivering global visibility, lifecycle automation, and actionable intelligence. + +The n8n Venafi TLS Protect Cloud node allows you to integrate with the [cloud-based Venafi TLS Protect](https://vaas.venafi.com/){:target=_blank} service. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/venafiTlsProtectCloud/). + +## Operations + +* Certificate + * Delete + * Download + * Get + * Get Many + * Renew +* Certificate Request + * Create + * Get + * Get Many + +## Related resources + +Refer to [Venafi's REST API documentation](https://docs.venafi.cloud/api/vaas-rest-api/){:target=_blank .external-link} for more information on this service. + +View [example workflows and related content](https://n8n.io/integrations/venafi-tls-protect-cloud/){:target=_blank .external-link} on n8n's website. + +n8n also provides: + +* A [trigger node](/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectcloudtrigger/) for Venafi TLS Protect Cloud. +* A [node](/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectdatacenter/) and [trigger node](/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectdatacentertrigger/) for Venafi TLS Protect Datacenter. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectdatacenter.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectdatacenter.md new file mode 100644 index 000000000..c8671047d --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectdatacenter.md @@ -0,0 +1,27 @@ +# Venafi TLS Protect Datacenter + +[Venafi](https://www.venafi.com/){:target=_blank .external-link} is a cybersecurity company providing services for machine identity management. They offer solutions to manage and protect identities for a wide range of machine types, delivering global visibility, lifecycle automation, and actionable intelligence. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/venafiTlsProtectDatacenter/). + +## Operations + +* Certificate + * Create + * Delete + * Download + * Get + * Get Many + * Renew +* Policy + * Get + +## Related resources + +View [example workflows and related content](https://n8n.io/integrations/venafi-tls-protect-datacenter/){:target=_blank .external-link} on n8n's website. + +n8n also provides: + +* A [trigger node](/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectdatacentertrigger/) for Venafi TLS Protect Datacenter. +* A [node](/integrations/builtin/app-nodes/n8n-nodes-base.venafiTlsProtectCloud/) and [trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectcloudtrigger/) node for Venafi TLS Protect Cloud. diff --git a/docs/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp.md b/docs/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp.md new file mode 100644 index 000000000..db0a9df32 --- /dev/null +++ b/docs/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp.md @@ -0,0 +1,22 @@ +# WhatsApp Business Platform + +[WhatsApp Business Platform](https://developers.facebook.com/docs/whatsapp/){:target=_blank .external-link} gives medium to large businesses the ability to connect with customers at scale. You can start conversations with customers in minutes, send customer care notifications or purchase updates, offer your customers a level of personalized service and provide support in the channel that your customers prefer to be reached on. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/whatsapp/). + +## Operations + +* Message + * Send + * Send Template +* Media + * Upload + * Download + * Delete + +## Related resources + +Refer to [WhatsApp Business Platform's Cloud API documentation](https://developers.facebook.com/docs/whatsapp/cloud-api){:target=_blank} for details about the operations. + +View [example workflows and related content](https://n8n.io/integrations/whatsapp-business-cloud/){:target=_blank .external-link} on n8n's website. diff --git a/docs/integrations/builtin/core-nodes/index.md b/docs/integrations/builtin/core-nodes/index.md index 039cc5a7e..4be788574 100644 --- a/docs/integrations/builtin/core-nodes/index.md +++ b/docs/integrations/builtin/core-nodes/index.md @@ -1,4 +1,4 @@ -# Overview +# Core nodes library This section provides information about n8n's core nodes. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.code.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.code.md new file mode 100644 index 000000000..213177221 --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.code.md @@ -0,0 +1,41 @@ +# Code + +The Code node allows you to write custom JavaScript and run it as a step in your workflow. + +!!! note "Function and Function Item nodes" + The Code node replaces the Function and Function Item nodes from version 0.198.0 onwards. If you're using an older version of n8n, you can still view the [Function node documentation](https://github.com/n8n-io/n8n-docs/blob/67935ad2528e2e30d7984ea917e4af2910a096ec/docs/integrations/builtin/core-nodes/n8n-nodes-base.function.md){:target=_blank .external-link} and [Function Item node documentation](https://github.com/n8n-io/n8n-docs/blob/67935ad2528e2e30d7984ea917e4af2910a096ec/docs/integrations/builtin/core-nodes/n8n-nodes-base.functionItem.md){:target=_blank .external-link}. + +## Choose a mode + +There are two modes: + +* **Run Once for All Items**: this is the default. When your workflow runs, the code in the code node executes once, regardless of how many input items there are. +* **Run Once for Each Item**: choose this if you want your code to run for every input item. + +## Supported JavaScript features + +The Code 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. + +## Data structure and item linking + +When working with the Code node, you need to understand the following concepts: + +* [Data structure](/data/data-structure/): understand the data you receive in the Code node, and requirements for outputting data from the node. +* [Item linking](/data/data-mapping/data-item-linking/): learn how data items work. You need to handle item linking when the number of input and output items doesn't match. + +## Built-in methods and variables + +n8n includes 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](/code-examples/methods-variables-reference/) for more information. + +## External libraries + +If you self-host n8n, you can import and use built-in and external npm modules in the Code node. To learn how to enable external modules, refer the [Configuration](/hosting/configuration/#use-built-in-and-external-modules-in-the-code-node) guide. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.comparedatasets.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.comparedatasets.md new file mode 100644 index 000000000..230b568ce --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.comparedatasets.md @@ -0,0 +1,23 @@ +# Compare Datasets + +The Compare Datasets node helps you compare data from two input streams. + +## Usage + +1. Decide which fields to compare. In **Input 1 Field**, enter the name of the field you want to use from input stream 1. In **Input 2 Field**, enter the name of the field you want to use from input stream 2. +2. **Optional**: you can compare by multiple fields. Select **Add Fields to Match** to set up more comparisons. +3. Choose how to handle differences between the datasets. In **When There Are Differences**, select one of the following: + * **Use Input 1 Version** + * **Use Input 2 Version** + * **Use a Mix of Versions** + * **Include Both Versions** + + +## Understand the output + +There are four output options: + +* **In 1 only Branch**: data that occurs only in the first input. +* **Same Branch**: data that is the same in both inputs. +* **Different Branch**: data that is different between inputs. +* **In 2 only Branch**: data that occurs only in the second output. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.crypto.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.crypto.md index 39a6c72bd..76d87dd7c 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.crypto.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.crypto.md @@ -13,8 +13,11 @@ You can configure further options for each action by selecting the type of encry - Type - MD5 - SHA256 - - SHA384 + - SHA3-256 + - SHA384 + - SHA3-384 - SHA512 + - SHA3-512 - Encoding - BASE64 - HEX diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.emailimap.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.emailimap.md new file mode 100644 index 000000000..f829f1c20 --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.emailimap.md @@ -0,0 +1,17 @@ +# Email Trigger (IMAP) + +The IMAP Email node allows you to receive emails using an IMAP email server. This node is a trigger node. + +!!! note "Credential" + You can find authentication information for this node [here](/integrations/builtin/credentials/imap/). + + +## Basic Operations + +- Receive an email + +## Node Reference + +- **Mailbox Name** field: The mailbox from which you want to receive emails. +- **Action** field: Used to specify whether an email should be marked as read when n8n receives it. +- **Download Attachment** field: Used to specify whether you want to download any attachments received with the emails. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeWorkflow.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeWorkflow.md index a35c534dd..f61dd3e68 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeWorkflow.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeWorkflow.md @@ -1,49 +1,29 @@ # Execute Workflow -The Execute Workflow node is used to run a different workflow on the host machine that runs n8n. +Use the Execute Workflow node to run a different workflow on the host machine that runs n8n. -## Node Reference +## Node reference The Execute Workflow node has two properties: -- ***Source***: This field is used to specify from where to get the workflow's information. +- **Source**: This field specifies from where to get the workflow's information. - Database - Local File - Parameter - URL -- ***Workflow***: This field contains information about the workflow, such as the workflow ID, URL, or a file. - - -## Example Usage - -This workflow allows you to execute another workflow on the host machine using the Execute Workflow node. You can also find the [workflow](https://n8n.io/workflows/588) on n8n.io. This example usage workflow would use the following nodes. -- [Start](/integrations/builtin/core-nodes/n8n-nodes-base.start/) -- [Execute Workflow]() - -The final workflow should look like the following image. - -![A workflow with the Execute Workflow node](/_images/integrations/builtin/core-nodes/executeworkflow/workflow.png) - -### 1. Start node - -The start node exists by default when you create a new workflow. - -### 2. Execute Workflow node - -1. Enter the ID of the workflow that you want to execute in the ***Workflow ID*** field. You can find instructions on how to obtain the ID of a workflow in the FAQs below. -2. Click on ***Execute Node*** to run the workflow. +- **Workflow**: This field contains information about the workflow, such as the workflow ID, URL, or a file. ## FAQs -### How do I find the workflow ID? +### How to find the workflow ID 1. Open the workflow for which you want to get the workflow ID. -2. Copy the number after `workflow/` in your URL and paste that in the ***Workflow ID*** field. +2. Copy the number after `workflow/` in your URL and paste that in the **Workflow ID** field. ### How does data get passed from one workflow to another? -Let's say, that there's a Execute Workflow node in **Workflow A**. The Execute Workflow node calls another workflow, **Workflow B**. +Let's say that there's a Execute Workflow node in **Workflow A**. The Execute Workflow node calls another workflow, **Workflow B**. - The Execute Workflow node passes the data to the Start node of **Workflow B**. - The last node of **Workflow B** sends the data back to the Execute Workflow node in **Workflow A**. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflowtrigger.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflowtrigger.md new file mode 100644 index 000000000..ae02f7b65 --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflowtrigger.md @@ -0,0 +1,10 @@ +# Execute Workflow Trigger + +Use this node to start a workflow in response to another workflow. It should be the first node in the workflow. + +n8n allows you to call workflows from other workflows. This is useful if you want to: + +* Reuse a workflow: for example, you could have multiple workflows pulling and processing data from different sources, then have all those workflows call a single workflow that generates a report. +* Break large workflows into smaller components. + +This node runs in response to a call from the [Execute Workflow](/integrations/builtin/core-nodes/n8n-nodes-base.executeWorkflow/) node. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.function.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.function.md deleted file mode 100644 index 042a47db0..000000000 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.function.md +++ /dev/null @@ -1,198 +0,0 @@ -# Function - -Using the function node, you can: - -* Transform data from other nodes -* Implement custom functionality - -!!! note "Function node and function item node" - Note that the Function node is different from the [Function Item](/integrations/builtin/core-nodes/n8n-nodes-base.functionItem/) node. Refer to [Data | Code](/data/code/) to learn about the difference between the two. - - -The Function node supports promises. So instead of returning the items directly, it is also possible to return a promise which resolves accordingly. - -The Function node supports writing to your browser console using `console.log`, useful for debugging and troubleshooting your workflows. - -## Data structure - -In n8n, all data passed between nodes is an array of objects. It has the following structure: - -```json -[ - { - // For most data: - // Wrap each item in another object, with the key 'json' - "json": { - // Example data - "jsonKeyName": "keyValue", - "anotherJsonKey": { - "lowerLevelJsonKey": 1 - } - }, - // For binary data: - // Wrap each item in another object, with the key 'binary' - "binary": { - // Example data - "binaryKeyName": { - "data": "....", // Base64 encoded binary data (required) - "mimeType": "image/png", // Best practice to set if possible (optional) - "fileExtension": "png", // Best practice to set if possible (optional) - "fileName": "example.png", // Best practice to set if possible (optional) - } - } - }, - ... -] -``` - -!!! note "Skipping the 'json' key and array syntax" - From 0.166.0 onwards, n8n automatically adds the `json` key if it's missing. It also automatically wraps your items in an array (`[]`) if needed. This is only when using the Function node. When building your own nodes, you must still make sure the node returns data with the `json` key. - - - - -## Example usage - -This workflow allows you to get today's date and day using the Function node. You can also find the [workflow](https://n8n.io/workflows/524) on the website. This example usage workflow would use the following two nodes. -- [Start](/integrations/builtin/core-nodes/n8n-nodes-base.start/) -- [Function]() - - -The final workflow should look like the following image. - -![A workflow with the Function node](/_images/integrations/builtin/core-nodes/function/workflow.png) - -### 1. Start node - -The start node exists by default when you create a new workflow. - -### 2. Function node - -1. Paste the following JavaScript code snippet in the *Function* field. -```javascript -var date = new Date().toISOString(); -var day = new Date().getDay(); -const weekday = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]; - -items[0].json.date_today = date; -items[0].json.day_today = weekday[day]; - -return items; -``` -2. Click on *Execute Node* to run the workflow. - - -## Node reference - -You can also use the methods and variables mentioned in the [Expressions](/code-examples/expressions/) page in the Function node. - -### Variable: items - -It contains all the items that the node has received as an input. - -Information about how the data is structured can be found on [this](/data/data-structure/) page about data structures. - -The data can be accessed and manipulated like this: - -```typescript -// Sets the JSON data property "myFileName" of the first item to the name of the -// file which is set in the binary property "image" of the same item. -items[0].json.myFileName = items[0].binary.image.fileName; - -return items; -``` - -This example creates 10 dummy items with the ids 0 to 9: - -```typescript -const newItems = []; - -for (let i=0;i<10;i++) { - newItems.push({ - json: { - id: i - } - }); -} - -return newItems; -``` - - -### Method: $item(index: number, runIndex?: number) - -With `$item` it is possible to access the data of parent nodes. That can be the item data but also -the parameters. It expects as input an index of the item the data should be returned for. This is -needed because for each item the data returned can be different. This is probably straightforward for the -item data itself but maybe less for data like parameters. The reason why it is also needed, is -that they may contain an expression. Expressions get always executed of the context for an item. -If that would not be the case, for example, the Email Send node not would be able to send multiple -emails at once to different people. Instead, the same person would receive multiple emails. - -The index is 0 based. So `$item(0)` will return the first item, `$item(1)` the second one, and so on. - -By default the item of the last run of the node will be returned. So if the referenced node ran -3x (its last runIndex is 2) and the current node runs the first time (its runIndex is 0) the -data of runIndex 2 of the referenced node will be returned. - -For more information about what data can be accessed via `$node`, check out the `Variable: $node` [section](/code-examples/expressions/variables/#variable-node). - -Example: - -```typescript -// Returns the value of the JSON data property "myNumber" of Node "Set" (first item) -const myNumber = $item(0).$node["Set"].json["myNumber"]; -// Like above but data of the 6th item -const myNumber = $item(5).$node["Set"].json["myNumber"]; - -// Returns the value of the parameter "channel" of Node "Slack". -// If it contains an expression the value will be resolved with the -// data of the first item. -const channel = $item(0).$node["Slack"].parameter["channel"]; -// Like above but resolved with the value of the 10th item. -const channel = $item(9).$node["Slack"].parameter["channel"]; -``` - - -### Method: getWorkflowStaticData(type) - -This gives access to the static workflow data. -It is possible to save data directly with the workflow. This data should, however, be very small. -A common use case is to for example to save a timestamp of the last item that got processed from -an RSS-Feed or database. It will always return an object. Properties can then read, delete or -set on that object. When the workflow execution succeeds, n8n will check automatically if the data -has changed and will save it, if necessary. - -There are two types of static data. The "global" and the "node" one. Global static data is the -same in the whole workflow. And every node in the workflow can access it. The node static data -, however, is different for every node and only the node which set it can retrieve it again. - -Example: - -```javascript -// Get the global workflow static data -const staticData = getWorkflowStaticData('global'); -// Get the static data of the node -const staticData = getWorkflowStaticData('node'); - -// Access its data -const lastExecution = staticData.lastExecution; - -// Update its data -staticData.lastExecution = new Date().getTime(); - -// Delete data -delete staticData.lastExecution; -``` - -It is important to know that the static data can not be read and written when testing via the UI. -The data there will always be empty and the changes will not persist. Only when a workflow -is active and it gets called by a Trigger or Webhook, the static data will be saved. - -## External libraries - -You can import and use built-in and external npm modules in the Function node. To learn how to enable external moduels, refer the [Configuration](/hosting/configuration/#use-built-in-and-external-modules-in-function-nodes) guide. - -## Further reading - - diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest.md index 626fa30bb..ab6112e40 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest.md @@ -1,165 +1,127 @@ # HTTP Request -The HTTP Request node is one of the most versatile nodes in n8n. It allows you to make HTTP requests to query data from apps and services. +The HTTP Request node is one of the most versatile nodes in n8n. It allows you to make HTTP requests to query data from any app or service with a REST API. -!!! note "Credential" - You can find authentication information for this node [here](/integrations/builtin/credentials/httpRequest/). +When using this node, you're creating a REST API call. You need some understanding of basic API terminology and concepts. +## Node fields -## Node Reference +### Method -- **Authentication:** there are two options for authentication. n8n recommends using the **Predefined credential type** option when it's available. It offers an easier way to set up and manage credentials, compared to configuring generic credentials. - - Select **Predefined Credential Type**. This allows you to perform custom operations, without additional authentication setup. For example, n8n has an Asana node, and supports using your Asana credentials in the HTTP Request node. Refer to [Custom API operations](/integrations/custom-operations/) for more information. - - Select **Generic Credential Type** to set up authentication using one of the following methods: - - Basic Auth - - Digest Auth - - Header Auth - - OAuth1 - - OAuth2 - - None - +Select the method to be used for the request: + +- DELETE +- GET +- HEAD +- OPTIONS +- PATCH +- POST +- PUT + +### URL + +Enter the endpoint you want to use. + +### Authentication + +There are two options for authentication. n8n recommends using the **Predefined credential type** option when it's available. It offers an easier way to set up and manage credentials, compared to configuring generic credentials. + +#### Predefined credentials + +Select **Predefined Credential Type**. This allows you to perform custom operations, without additional authentication setup. For example, n8n has an Asana node, and supports using your Asana credentials in the HTTP Request node. Refer to [Custom API operations](/integrations/custom-operations/) for more information. + +#### Generic credentials + +Select **Generic Credential Type** to set up authentication using one of the following methods: + +- Basic Auth +- Digest Auth +- Header Auth +- OAuth1 +- OAuth2 +- None +Refer to [HTTP request credentials](/integrations/builtin/credentials/httpRequest/) for more information setting up each credential type. -- **Request Method:** Select the method to be used for the request: - - DELETE - - GET - - HEAD - - PATCH - - POST - - PUT -- **URL**: The full URL of the request. -- **Ignore SSL Issues**: Download the response even if SSL validation isn't possible. -- **Response Format**: Select the format in which the data gets returned from the URL. You can choose between File, JSON, and String. -- **JSON/RAW Parameters**: Whether to set the body/query parameter using the value-key pair UI (disabled) or JSON/RAW (enabled). When using JSON/RAW, the **Header** field requires a JSON object. Refer to [Examples - Create a JSON/RAW header object](#create-a-jsonraw-header-object) for more information. -- **Options**: - - **Batch Interval**: The time (in milliseconds) between each batch of requests. Set to `0` to disable. - - **Batch Size**: If set, n8n splits input in batches to throttle requests. Use `-1` to disable. n8n treats `0` as `1`. - - **Full Response**: Retrieve the full response instead of just the body from the URL. - - **Follow Redirect**: Follow any redirects with a status code `3xx`. - - **Ignore Response Code**: Let the node execute even when the HTTP status code isn't 2xx. - - **Proxy**: Specify an HTTP proxy that you may want to use. - - **Split Into Items**: Flatten the node output as a simple array. See the [Examples](#examples) section to learn more. - - **Timeout:** The maximum time (in ms) to wait for a response header from the server before aborting the request. - - **Use Querystring**: Set this option to `true` if you need arrays serialized as `foo=bar&foo=baz` instead of the default `foo[0]=bar&foo[1]=baz`. - - **Headers**: Specify any optional HTTP request headers you may want to include with your request. - - **Query Parameters**: Specify any HTTP query parameters you may want to include with your request. +### Parameters, headers, and body -## Example usage +You can choose to send additional information with your request. The data you need to send depends on the API you're interacting with, and the type of request you're making. Refer to your service's API documentation for detailed guidance. -This workflow allows you to GET a sample list of users from [reqres.in](https://reqres.in/), add a new user using a POST request, and update the user using a PATCH request. You can also find the [workflow](https://n8n.io/workflows/602) on n8n.io. This example usage workflow uses the following nodes. - -- [Start](/integrations/builtin/core-nodes/n8n-nodes-base.start/) -- [HTTP Request]() - -The final workflow should look like the following image. - -![A workflow with the HTTP Request node](/_images/integrations/builtin/core-nodes/httprequest/workflow.png) - -### Step 1: Start node - -The start node exists by default when you create a new workflow. +* **Send Query Parameters**: include query parameters. Query parameters are usually used as filters or searches on your query. +* **Send Headers**: include request headers. Headers contain metadata about your request. +* **Send Body**: send additional information in the body of your request. -### Step 2: HTTP Request node (GET) +### Options -1. Enter `https://reqres.in/api/users` in the **URL** field. -2. Click on **Execute Node** to run the workflow. +Select **Add Option** to view and select these options. -![Get a list of sample users using the HTTP Request node](/_images/integrations/builtin/core-nodes/httprequest/httprequest_node.png) +- **Batching**: control how to batch large responses. +- **Ignore SSL Issues**: download the response even if SSL validation isn't possible. +- **Redirects**: choose whether to follow redirects. Disabled by default. +- **Response**: provide settings about the expected API response. +- **Proxy**: use this if you need to specify an HTTP proxy. +- **Timeout**: set a timeout for the request. -### Step 3: HTTP Request1 node (POST) +## Basic example -1. Select **POST** from the **Request Method** dropdown list. -2. Enter `https://reqres.in/api/users` in the **URL** field. -3. Click on the **Add Parameter** button in the *Body Parameters* section. -4. Enter `name` in the **Name** field. -5. Enter `Neo` in the **Value** field. -6. Click on the **Add Parameter** button in the *Body Parameters* section. -7. Enter `job` in the **Name** field. -8. Enter `Programmer` in the **Value** field. -9. Click on **Execute Node** to run the workflow. +This example uses [Reqres](https://reqres.in/){:target=_blank .external-link}, a service for testing APIs with fake data. It provides a basic usage example. -![Create a user using the HTTP Request node](/_images/integrations/builtin/core-nodes/httprequest/httprequest1_node.png) +### Setup +Create a new workflow and add the HTTP Request node. -### Step 4: HTTP Request2 node (PATCH) +Enter `https://reqres.in/api/users` in the **URL** field. All the examples call this endpoint. -1. Select **PATCH** from the **Request Method** dropdown list. -2. Enter `https://reqres.in/api/users/2` in the **URL** field. -3. Click on the **Add Parameter** button in the **Body Parameters** section. -4. Enter `name` in the **Name** field. -5. Enter `Neo` in the **Value** field. -6. Click on the **Add Parameter** button in the **Body Parameters** section. -7. Enter `job` in the **Name** field. -8. Enter `The Chosen One` in the **Value** field. -9. Click on **Execute Node** to run the workflow. +### Get a list of users -![Update a user using the HTTP Request node](/_images/integrations/builtin/core-nodes/httprequest/httprequest2_node.png) +Ensure the **Method** is set to **GET**. -## Examples +Select **Execute node**. n8n calls the `users` endpoint of the Reqres API, and outputs the response. + +### Add a user + +1. Select **POST** in the **Method** dropdown list. +2. Enable **Send Body**. +3. Enter `name` in the **Name** field. +4. Enter `Neo` in the **Value** field. +5. Select **Add Parameter** +6. Enter `job` in the **Name** field. +7. Enter `Programmer` in the **Value** field. +8. Select **Execute node** to run the workflow. n8n calls the `users` endpoint of the Reqres API, and outputs the response. + +## More examples ### Fetch a binary file from a URL -1. Enter the URL of the file in the **URL** field. For example, you can enter `https://n8n.io/n8n-logo.png` to fetch the n8n logo. -2. Select **File** from the **Response Format** dropdown list. -3. (Optional) Change the binary property value in the **Binary Property** field. Throughout the workflow, you can refer to the binary data with the value you set in this field. -4. Click on **Execute Node** to run the node. -5. After the node gets executed, click on the **Binary** tab. -6. Click on the **Show Binary Data** button to view the file. +1. Enter the URL of the file in the **URL** field. For example, you can enter `https://docs.n8n.io/_images/n8n-docs-icon.svg` to fetch the n8n logo. +2. Select **Add Option > Response**. +3. Set **Response Format** to **File**. +4. Select **Execute node** to run the node. ### Send a binary file to an API endpoint -Depending on your use-case, you might want to send a binary file to an API endpoint. To do that, follow the steps mentioned below. +1. Connect the HTTP Request node with a node that has previously fetched the binary file. For example, this could be an HTTP Request node, [Read Binary File](/integrations/builtin/core-nodes/n8n-nodes-base.readBinaryFile/) node, [Google Drive](/integrations/builtin/app-nodes/n8n-nodes-base.googleDrive/) node, and so on. +2. Select **POST** in the **Method** dropdown. Check the API documentation of your API to make sure that you have selected the correct HTTP request method. +3. Enter the URL you want to send the binary file to in the **URL** field. +4. Enable **Send Body**. +5. In **Body Content Type**, select **n8n Binary Data**. +6. In **Input Data Field Name**, enter the name of the field containing the binary data. +9. Select **Execute node** to run the node. -1. Connect the HTTP Request node with a node that has previously fetched the binary file. This node can be an HTTP Request node, [Read Binary File](/integrations/builtin/core-nodes/n8n-nodes-base.readBinaryFile/) node, [Google Drive](/integrations/builtin/app-nodes/n8n-nodes-base.googleDrive/) node or any such node. -2. Select **POST** from the **Request Method** dropdown list. Check the API documentation of your API to make sure that you have selected the correct HTTP request method. -3. Enter the URL where you want to send the binary file in the **URL** field. -4. Toggle **JSON/RAW Parameters** to `true`. -5. Toggle **Send Binary Data** to `true`. -6. Click on **Add Option** and select **Body Content Type** from the dropdown list. -7. Select **Form-Data Multipart** from the **Body Content Type** dropdown list. -8. If you are referring to the binary property with a different value, enter that value in the **Binary Property** field (name displayed in the binary tab after executing the previous node). To set a name for the form field, separate the field name with a colon, example `sendKey:binaryProperty`. If you want to send multiple files, separate them with comma, example: `sendKey1:binaryProperty1,sendKey2:binaryProperty2` -9. Click **Execute Node** to run the node. - -Refer to this example [workflow](https://n8n.io/workflows/1338). +Refer to this [workflow template](https://n8n.io/workflows/1338-update-twitter-banner-using-http-request/){:target=_blank .external link} for a full example. ### Get the HTTP status code after an execution -1. Click on **Add Option** and select 'Full Response'. -2. Toggle **Full Response** to `true`. +1. Select **Add Option** > **Response**. +2. Enable **Include Response Headers and Status**. -When the node gets executed, you will receive the HTTP status code, the HTTP status message, and the header parameters. +When you execute the node, n8n includes the headers, status code, and status message in the output. ### Send XML data -1. Toggle **JSON/RAW Parameters** to `true`. -2. Click on **Add Option** and select 'Body Content Type'. -3. Select **RAW/Custom** from the **Body Content Type** field. +1. Enable **Send Body**. +2. In **Body Content Type**, select **Raw**. +3. In **Content Type**, enter `application/xml`. 4. Enter the XML data in the **Body** field. - -### When to use the Split Into Items parameter - -Not all incoming data has the [structure](/data/data-structure/) needed to allow nodes to [process](/data/data-structure/#data-flow) each individual item. With most nodes, you must use the Item List node to change data structure. The HTTP Request node allows you to do this automatically by enabling the **Split Into Items** parameter. - -### Create a JSON/RAW header object - -When you enable **JSON/RAW Parameters**, you must provide the **Headers** field as a JSON object. To do this, use the expressions editor to write the JSON. - -For example, to send a header named "Example header", with a value of "Test value": - -1. Open the expressions editor for the **Headers** field. -2. Enter the following expression: - ```js - // Note the spacing between the opening expression brackets - // and the opening JSON brackets - {{ {"Example header":"Test value"} }} - ``` -3. Close the expressions editor to return to the node view. The header object is visible in the **Headers** field. - -!!! warning "You must use the expressions editor" - You must use the expressions editor to create your JSON object. Writing JSON directly in the **Headers** field is invalid. - - - - diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.if.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.if.md index 6ee108695..04858af8e 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.if.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.if.md @@ -35,7 +35,9 @@ You can add comparison conditions using the **Add Condition** dropdown. Conditio You can choose to split a workflow when any of the specified conditions are met, or only when all the specified conditions are met using the options in the **Combine** dropdown list. ---8<-- "_snippets/integrations/builtin/core-nodes/if-merge-branch-execution.md" +## Branch execution with If and Merge nodes + +--8<-- "_snippets/integrations/builtin/core-nodes/merge/if-merge-branch-execution.md" ## Example Usage diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail.md deleted file mode 100644 index c7def30ff..000000000 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail.md +++ /dev/null @@ -1,36 +0,0 @@ -# IMAP Email - -The IMAP Email node is used to receive emails via an IMAP email server. This node is a trigger node. - -!!! note "Credential" - You can find authentication information for this node [here](/integrations/builtin/credentials/imap/). - - -## Basic Operations - -- Receive an email - -## Node Reference - -- ***Mailbox Name*** field: The mailbox from which you want to receive emails. -- ***Action*** field: Used to specify whether or not an email should be marked as read when n8n receives it. -- ***Download Attachment*** field: Used to specify whether or not you want to download any attachments received with the emails. - -## Example Usage - -This workflow allows you to receive an email using the IMAP Email node. You can also find the [workflow](https://n8n.io/workflows/587) on the website. This example usage workflow would use the following two nodes. -- [IMAP Email]() - -The final workflow should look like the following image. - -![A workflow with the IMAP Email node](/_images/integrations/builtin/core-nodes/imapemail/workflow.png) - -### 1. IMAP Email node - -1. First of all, you'll have to enter credentials for the IMAP Email node. You can find out how to do that [here](/integrations/builtin/credentials/imap/). -2. Enter the name of the mailbox from which you want to receive emails in the ***Mailbox Name*** field. -3. Click on ***Execute Node*** to run the workflow. - - - - diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger.md new file mode 100644 index 000000000..6c4c78b87 --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger.md @@ -0,0 +1,5 @@ +# Manual Trigger + +Use this node if you want to start a workflow by selecting **Execute Workflow**, and don't want any option for the workflow to run automatically. + +Workflows always need a trigger (start point). In most cases, a trigger node starts the workflow in response to an external event. However, you still need a trigger node even when starting the workflow manually. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.merge.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.merge.md index 83875dc31..3c1e34db7 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.merge.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.merge.md @@ -1,66 +1,95 @@ # Merge -Use the Merge node to combine data from multiple streams, once data of both streams is available. +Use the Merge node to combine data from two streams, once data of both streams is available. -## Node Reference +!!! note "Major changes in 0.194.0" + This node was overhauled in n8n 0.194.0. This document reflects the latest version of the node. If you're using an older version of n8n, you can find the previous version of this document [here](https://github.com/n8n-io/n8n-docs/blob/4ff688642cc9ee7ca7d00987847bf4e4515da59d/docs/integrations/builtin/core-nodes/n8n-nodes-base.merge.md){:target=_blank .external-link}. -### Merge mode +## Merge mode You can specify how the Merge node should combine data from different branches. The following options are available: -- **Append:** Combines data of both inputs. The output will contain items of input 1 and input 2. -- **Keep Key Matches:** Keeps data of input 1 if it finds a match with data of input 2. -- **Merge By Index:** Merges data of both the inputs. The output will contain the data of input 1 merged with the data of input 2. The merge occurs based on the index of the items. For example, the first item of input 1 will be merged with the first item of input 2. -- **Merge By Key:** Merges data of both the inputs. The output will contain the data of input 1 merged with the data of input 2. The merge occurs depending on a defined key. -- **Multiples:** Merges each value of one input with each value of the other input. The output will contain (m*n) items where (m) and (n) are lengths of the inputs. -- **Pass-through:** Passes through the data of one input. The output will contain items of the defined input. -- **Remove Key Matches:** Keeps the data of input 1 if it doesn't find a match with the data of input 2. -- **Wait:** Waits till the data of both the inputs is available. It will then output a single empty item. +### Append ---8<-- "_snippets/integrations/builtin/core-nodes/if-merge-branch-execution.md" +Keep data from both inputs. The output contains items from Input 1, followed by all items from Input 2. -### Additional Fields +![Diagram](/_images/integrations/builtin/core-nodes/merge/append-diagram.png) -- **Property Input 1:** The name of the property which decides which items of input 1 to merge. This field is displayed when 'Keep Key Matches', 'Merge By Key', or 'Remove Key Matches' is selected in the **Mode** dropdown list. -- **Property Input 2:** The name of the property which decides which items of input 2 to merge. This field is displayed when 'Keep Key Matches', 'Merge By Key', or 'Remove Key Matches' is selected in the **Mode** dropdown list. -- **Join:** Use this to specify how many items the output should contain if inputs contain different amount of items. This field is displayed when 'Merge By Index' is selected in the **Mode** dropdown list. You can select from the following options. - - **Inner Join:** Merges as many items as both the inputs contains. For example, if input 1 contains 3 items and input 2 contains 3 items, the output will contain 3 items. - - **Left Join:** Merges as many items as the first input contains. For example, if input 1 contains 3 items and input 2 contains 5 items, the output will contain 3 items. - - **Outer Join:** Merges as many items as input contains with most items. For example, if input 1 contains 3 items and input 2 contains 5 items, the output will contain 5 items. -- **Overwrite:** Select when to overwrite the values from Input1 with values from Input 2. This field is displayed when 'Merge By Key' is selected from the **Mode** dropdown list. You can select from the following options. - - **Always:** Always overwrites everything. - - **If Blank:** Overwrites only values of 'null', 'undefined' or the empty strings. - - **If Missing:** Only adds values which don't exist yet. -- **Output Data:** Defines which input data should be used as the output of the node. This field is displayed when 'Pass-through' is selected from the **Mode** dropdown list. You can select from the following options. - - **Input 1** - - **Input 2** +### Combine -### Merging branches with uneven numbers of items +Combine data from both inputs. Choose a **Combination Mode** to control how n8n merges the data. + +#### Merge by fields + +Compare items by field values. Enter the fields you want to compare in **Fields to Match**. + +n8n's default behavior is to keep matching items. You can change this using the **Output Type** setting: + +* Keep matches: merge items that match. +* Keep non-matches: merge items that don't match. +* Enrich Input 1: keep all data from Input 1, and add matching data from Input 2. +* Enrich Input 2: keep all data from Input 2, and add matching data from Input 1. + +![Diagram](/_images/integrations/builtin/core-nodes/merge/merge-by-field-diagram.png) + + +##### Field value clashes + +--8<-- "_snippets/integrations/builtin/core-nodes/merge/field-value-clash.md" + +##### Multiple matches + +Matching by field can generate multiple matches if the inputs contain duplicate data. To handle this, select **Add Option > Multiple Matches**. Then choose: + +* **Include All Matches**: output multiple items (one for each match). +* **Include First Match Only**: keep the first item, discard subsequent items. + + +#### Merge by position + +Combine items based on their order. The item at index 0 in Input 1 merges with the item at index 0 in Input 2, and so on. + +![Diagram](/_images/integrations/builtin/core-nodes/merge/merge-by-position-diagram.png) + +##### Inputs with different numbers of items + +If there are more items in one input than the other, the default behavior is to leave out the items without a match. Choose **Add Option** > **Include Any Unpaired Items** to keep the unmatched items. + +##### Field value clashes + +--8<-- "_snippets/integrations/builtin/core-nodes/merge/field-value-clash.md" + +#### Multiplex + +Output all possible item combinations, while merging fields with the same name. + +![Diagram](/_images/integrations/builtin/core-nodes/merge/multiplex-diagram.png) + +##### Field value clashes + +--8<-- "_snippets/integrations/builtin/core-nodes/merge/field-value-clash.md" + +### Choose branch + +Choose which input to keep. This option always waits until the data from both inputs is available. You can keep the data from Input 1 or Input 2, or you can output a single empty item. The node outputs the data from the chosen input, without changing it. + +## Merging branches with uneven numbers of items The items passed into Input 1 of the Merge node will take precedence. For example, if the Merge node receives five items in Input 1 and 10 items in Input 2, it only processes five items. The remaining five items from Input 2 aren't processed. ---8<-- "_snippets/integrations/builtin/core-nodes/if-merge-branch-execution.md" +## Branch execution with If and Merge nodes -## Example Usage - -This workflow allows you to merge greetings for the users based on their associated language using the Merge node. You can also find the [workflow](https://n8n.io/workflows/655) on n8n.io. This example usage workflow uses the following nodes. - -- [Start](/integrations/builtin/core-nodes/n8n-nodes-base.start/) -- [Function](/integrations/builtin/core-nodes/n8n-nodes-base.function/) -- [Merge]() - -The final workflow should look like the following image. - -![A workflow with the HTML Extract node](/_images/integrations/builtin/core-nodes/merge/workflow.png) - -### 1. Start node - -The start node exists by default when you create a new workflow. +--8<-- "_snippets/integrations/builtin/core-nodes/merge/if-merge-branch-execution.md" -### 2. Function node +## Try it out: a step by step example -1. Paste the following JavaScript code snippet in the **Function** field. +Create a simple workflow with some example input data to try out the Merge node. + +### Set up sample data using the Function nodes + +1. Add a Function node to the canvas and connect it to the Start node. +2. Paste the following JavaScript code snippet in the **JavaScript Code** field: ```js return [ { @@ -83,47 +112,86 @@ return [ } ]; ``` -2. Click on **Execute Node** to run the node. - -![Generate users information using the Function node](/_images/integrations/builtin/core-nodes/merge/function_node.png) - - -### 3. Function1 node - -1. Paste the following JavaScript code snippet in the **Function** field. +3. Add a second Function node, and connect it to the Start node. +4. Paste the following JavaScript code snippet in the **JavaScript Code** field: ```js return [ + { + json: { + greeting: 'Hello', + language: 'en', + } + }, { json: { greeting: 'Hallo', language: 'de', } - }, - { - json: { - greeting: 'Hello', - language: 'en', - } } ]; ``` -2. Click on **Execute Node** to run the node. + +### Try out different merge modes + +Add the Merge node. Connect the first Function node to **Input 1**, and the second Function node to **Input 2**. Run the workflow to load data into the Merge node. + +The final workflow should look like the following image. + +![Simple merge workflow with two function nodes](/_images/integrations/builtin/core-nodes/merge/workflow.png) + +Now try different options in **Mode** to see how it affects the output data. + +#### Append + +Select **Mode** > **Append**, then select **Execute node**. + +Output data in table view: + +![Append mode output](/_images/integrations/builtin/core-nodes/merge/append-mode.png) -![Generate greetings information using the Function node](/_images/integrations/builtin/core-nodes/merge/function1_node.png) +#### Merge by fields + +You can merge these two data inputs so that each person gets the correct greeting for their language. + +1. Select **Mode** > **Merge By Fields**. +2. In both **Input 1 Field** and **Input 2 Field**, enter `language`. This tells n8n to combine the data by matching the values in the `language` field in each data set. +3. Select **Execute node**. + +Output in table view: + +![Merge by Fields mode output](/_images/integrations/builtin/core-nodes/merge/merge-by-fields-mode.png) -### 4. Merge node (mergeByKey) +#### Merge by position -1. Select 'Merge By Key' from the **Mode** dropdown list. -2. Enter `language` in the **Property Input 1** field. -3. Enter `language` in the **Property Input 2** field. -4. Click on **Execute Node** to run the node. +Select **Mode** > **Merge By Position**, then select **Execute node**. + +Default output in table view: + +![Merge by Position mode output](/_images/integrations/builtin/core-nodes/merge/merge-by-position-mode-default.png) -![Merge user information and greetings information using the Merge node](/_images/integrations/builtin/core-nodes/merge/merge_node.png) +##### Keep unpaired items + +If you want to keep all items, select **Add Option** > **Include Any Unpaired Items**, then enable **Include Any Unpaired Items**. + +Output with unpaired items in table view: + +![Merge by Position mode with unpaired items output](/_images/integrations/builtin/core-nodes/merge/merge-by-position-include-unpaired.png) +#### Multiplex + +Select **Mode** > **Multiplex**, then select **Execute node**. + +Output in table view: + +![Merge by Multiplex mode output](/_images/integrations/builtin/core-nodes/merge/multiplex-mode.png) +## Try it out: load a workflow +n8n provides an example workflow that demonstrates key Merge node concepts. + +Go to [Joining different datasets](https://n8n.io/workflows/1747/){:target=_blank .external-link} and select **Use workflow** to copy the example workflow. You can then paste it into your n8n instance. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.n8n.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.n8n.md new file mode 100644 index 000000000..a4f20560f --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.n8n.md @@ -0,0 +1,32 @@ +# n8n + +A node to integrate with n8n itself. This node allows you to consume the [n8n API](/api/) in your workflows. + +## Related resources + +### Credentials + +Refer to the [API authentication](/api/authentication/) documentation for guidance on getting your n8n credentials. + +### Examples + +Refer to the [n8n node on the website](https://n8n.io/integrations/n8n/) for a list of examples. + +## Operations + +* Credential + * Create + * Delete + * Get Schema +* Execution + * Get + * Get Many + * Delete +* Workflow + * Activate + * Create + * Deactivate + * Delete + * Get + * Get Many + * Update diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger.md new file mode 100644 index 000000000..d0e52bd85 --- /dev/null +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger.md @@ -0,0 +1,52 @@ +# Schedule Trigger + +Use the Schedule Trigger node run workflows at fixed intervals and times. This works in a similar way to the cron software utility in Unix-like systems. + +!!! note "Cron node" + The Code node replaces the Cron node from version 0.199.0 onwards. If you're using an older version of n8n, you can still view the [Cron node documentation](https://github.com/n8n-io/n8n-docs/blob/67935ad2528e2e30d7984ea917e4af2910a096ec/docs/integrations/builtin/core-nodes/n8n-nodes-base.cron.md){:target=_blank .external-link}. + +!!! note "Keep in mind" + 1. If a workflow uses the Schedule node as a trigger, make sure that you save and activate the workflow. + 2. Set the timezone correctly for the n8n instance (or the workflow). + + +## Schedule your workflow + +Select an interval in **Trigger Interval**. Once you select an interval, n8n displays more options to customize that interval. + +### Example + +In this example, schedule a workflow to run once a quarter, at the end of the quarter, at 09:00. + +1. In **Trigger Interval**, select **Months**. +2. Change **Months Between Triggers** to `3`. +3. To run the workflow at the end of the month, change **Trigger at Day of Month** to `28`. +4. Change **Trigger at Hour** to **9am**. Leave **Trigger at Minute** as its default, `0`. + +Note that the Schedule Trigger uses the workflow timezone if available. Otherwise it uses the n8n instance timezone. + +## Generate a custom cron expression + +If you need a custom time setting, select **Trigger Interval** > **Custom (Cron)**. + +To generate a cron expression, you can use [crontab guru](https://crontab.guru){:target=_blank .external-link}. Paste the cron expression that you generated using crontab guru in the **Expression** field in n8n. + +### Examples + +If you want to trigger your workflow every day at 04:08:30, enter the following in the **Cron Expression** field. +``` +30 8 4 * * * +``` + +If you want to trigger your workflow every day at 04:08, enter the following in the **Cron Expression** field. +``` +8 4 * * * +``` + +### Why there are six asterisks (*) in the cron expression? + +The sixth asterisk in the cron expression represents seconds. Setting this is optional. The node will execute even if you don't set the value for seconds. + +| * | * | * | * | * | * | +|---|---|---|---|---|---| +|second|minute|hour|day|week|month| diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.sendEmail.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.sendEmail.md index 6200a4434..728bfd984 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.sendEmail.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.sendEmail.md @@ -19,7 +19,7 @@ The Send Email node is used to send an email via an SMTP email server. ## Node Reference - **From Email:** The email address you are sending from. -- **To Email:** The recipient email address. +- **To Email:** The recipient email address. Multiple recipients can be separated using a comma. - **CC Email:** A field that can be used to specify an email address for a carbon copy of the email. - **BCC Email:** A field that can be used to specify an email address for a blind carbon copy of the email. - **Subject:** The subject of your message. diff --git a/docs/integrations/builtin/core-nodes/n8n-nodes-base.start.md b/docs/integrations/builtin/core-nodes/n8n-nodes-base.start.md index 5b0abbdaf..ec76180d1 100644 --- a/docs/integrations/builtin/core-nodes/n8n-nodes-base.start.md +++ b/docs/integrations/builtin/core-nodes/n8n-nodes-base.start.md @@ -1,5 +1,8 @@ # Start +!!! warning "Deprecated" + The Start node was removed from n8n in 0.199.0. It is still available in legacy workflows. + The start node is the first node in a workflow. It exists by default when you create a new workflow and looks like the following image. ![A new workflow with the Start node](/_images/integrations/builtin/core-nodes/start/workflow.png) diff --git a/docs/integrations/builtin/credentials/actionNetwork.md b/docs/integrations/builtin/credentials/actionnetwork.md similarity index 100% rename from docs/integrations/builtin/credentials/actionNetwork.md rename to docs/integrations/builtin/credentials/actionnetwork.md diff --git a/docs/integrations/builtin/credentials/activeCampaign.md b/docs/integrations/builtin/credentials/activecampaign.md similarity index 100% rename from docs/integrations/builtin/credentials/activeCampaign.md rename to docs/integrations/builtin/credentials/activecampaign.md diff --git a/docs/integrations/builtin/credentials/acuityScheduling.md b/docs/integrations/builtin/credentials/acuityscheduling.md similarity index 100% rename from docs/integrations/builtin/credentials/acuityScheduling.md rename to docs/integrations/builtin/credentials/acuityscheduling.md diff --git a/docs/integrations/builtin/credentials/adalo.md b/docs/integrations/builtin/credentials/adalo.md new file mode 100644 index 000000000..36ea6edca --- /dev/null +++ b/docs/integrations/builtin/credentials/adalo.md @@ -0,0 +1,19 @@ +# Adalo + +You can use these credentials to authenticate the following nodes with Adalo: + +* [Adalo node](/integrations/builtin/app-nodes/n8n-nodes-base.adalo/) + +## Prerequisites + +* An Adalo account +* An API key. Follow [Adalo's API documentation](https://help.adalo.com/integrations/the-adalo-api/collections){:target=_blank .external-link} to get your key. +* Your Adalo app ID. + +## API key + +--8<-- "_snippets/integrations/builtin/credentials/open-credential-modal-list.md" + +1. Copy the API key from Adalo into **API Key**. +1. Copy the App ID for your Adalo app into **App ID**. +1. Select **Save**. n8n tests your credentials and confirms that they work. diff --git a/docs/integrations/builtin/credentials/agileCrm.md b/docs/integrations/builtin/credentials/agilecrm.md similarity index 100% rename from docs/integrations/builtin/credentials/agileCrm.md rename to docs/integrations/builtin/credentials/agilecrm.md diff --git a/docs/integrations/builtin/credentials/apiTemplateIo.md b/docs/integrations/builtin/credentials/apitemplateio.md similarity index 100% rename from docs/integrations/builtin/credentials/apiTemplateIo.md rename to docs/integrations/builtin/credentials/apitemplateio.md diff --git a/docs/integrations/builtin/credentials/aws.md b/docs/integrations/builtin/credentials/aws.md index 6831e947f..694fdb99f 100644 --- a/docs/integrations/builtin/credentials/aws.md +++ b/docs/integrations/builtin/credentials/aws.md @@ -2,7 +2,9 @@ You can use these credentials to authenticate the following nodes with AWS. +- [AWS Certificate Manager](/integrations/builtin/app-nodes/n8n-nodes-base.awsCertificateManager/) - [AWS DynamoDB](/integrations/builtin/app-nodes/n8n-nodes-base.awsDynamoDb/) +- [AWS Elastic Load Balancing](/integrations/builtin/app-nodes/n8n-nodes-base.awsElb/) - [AWS Lambda](/integrations/builtin/app-nodes/n8n-nodes-base.awsLambda/) - [AWS Rekognition](/integrations/builtin/app-nodes/n8n-nodes-base.awsRekognition/) - [AWS S3](/integrations/builtin/app-nodes/n8n-nodes-base.awsS3/) @@ -15,22 +17,22 @@ You can use these credentials to authenticate the following nodes with AWS. ## Prerequisites -Create an [AWS](https://aws.amazon.com/) account. +Create an [AWS](https://aws.amazon.com/){:target=_blank .external-link} account. ## Using Access Token -1. Open your [AWS Management Console](https://console.aws.amazon.com). +1. Open your [AWS Management Console](https://console.aws.amazon.com){:target=_blank .external-link}. 2. Click on your name on the top right and select 'My Security Credentials' from the dropdown. -3. Click on the ***Create New Access Key*** button, under the ***Access keys (access key ID and secret access key)*** section -4. Click on the ***Show Access Key*** button. +3. Click on the **Create New Access Key** button, under the **Access keys (access key ID and secret access key)** section +4. Click on the **Show Access Key** button. 5. Copy the displayed Access Key ID. -6. Enter the name for your credentials in the ***Credentials Name*** field in the 'AWS' credentials in n8n. -7. Paste the Access Key ID in the ***Access Key ID*** field in the 'AWS' credentials in n8n. +6. Enter the name for your credentials in the **Credentials Name** field in the 'AWS' credentials in n8n. +7. Paste the Access Key ID in the **Access Key ID** field in the 'AWS' credentials in n8n. 8. Copy the secret access key from your AWS console. -9. Paste the secret access key in the ***Secret Access Key*** field in the 'AWS' credentials in n8n. -10. Click the ***Create*** button to save your credentials in n8n. +9. Paste the secret access key in the **Secret Access Key** field in the 'AWS' credentials in n8n. +10. Click the **Create** button to save your credentials in n8n. -**Note:** If you're running your AWS instance in a different region, please update the ***Region*** field accordingly. +**Note:** If you're running your AWS instance in a different region, please update the **Region** field accordingly. The following video demonstrates the steps mentioned above. diff --git a/docs/integrations/builtin/credentials/bambooHr.md b/docs/integrations/builtin/credentials/bamboohr.md similarity index 100% rename from docs/integrations/builtin/credentials/bambooHr.md rename to docs/integrations/builtin/credentials/bamboohr.md diff --git a/docs/integrations/builtin/credentials/baserow.md b/docs/integrations/builtin/credentials/baserow.md index dd235592f..d8b6e30d3 100644 --- a/docs/integrations/builtin/credentials/baserow.md +++ b/docs/integrations/builtin/credentials/baserow.md @@ -13,7 +13,7 @@ or a self hosted instance. 1. In n8n, open the **Credentials** menu item and click on **New** 2. In the **Add new credential** dialogue, select **Baserow API** and click on the **Continue** button -3. If using the online version of Baserow, leave the **Host** as `https://api/baserow.io`, otherwise set it to your self-hosted instance API URL. +3. If using the online version of Baserow, leave the **Host** as `https://api.baserow.io`, otherwise set it to your self-hosted instance API URL. 4. Enter your Baserow username in the **Username** field 5. Enter your Baserow password in the **Password** field 6. Click on the **Save** button diff --git a/docs/integrations/builtin/credentials/circleCi.md b/docs/integrations/builtin/credentials/circleci.md similarity index 100% rename from docs/integrations/builtin/credentials/circleCi.md rename to docs/integrations/builtin/credentials/circleci.md diff --git a/docs/integrations/builtin/credentials/ciscoWebex.md b/docs/integrations/builtin/credentials/ciscowebex.md similarity index 100% rename from docs/integrations/builtin/credentials/ciscoWebex.md rename to docs/integrations/builtin/credentials/ciscowebex.md diff --git a/docs/integrations/builtin/credentials/citrixadc.md b/docs/integrations/builtin/credentials/citrixadc.md new file mode 100644 index 000000000..3cf9ac12e --- /dev/null +++ b/docs/integrations/builtin/credentials/citrixadc.md @@ -0,0 +1,11 @@ +# Citrix ADC + +You can use these credentials to authenticate the following nodes with Citrix ADC: + +* [Citrix ADC node](/integrations/builtin/app-nodes/n8n-nodes-base.citrixAdc/) + +Enter the following information in the **Citrix ADC account** credentials modal: + +* The URL of your Citrix ADC instance +* Username +* Password diff --git a/docs/integrations/builtin/credentials/clickUp.md b/docs/integrations/builtin/credentials/clickup.md similarity index 100% rename from docs/integrations/builtin/credentials/clickUp.md rename to docs/integrations/builtin/credentials/clickup.md diff --git a/docs/integrations/builtin/credentials/cloudflare.md b/docs/integrations/builtin/credentials/cloudflare.md new file mode 100644 index 000000000..e372b001d --- /dev/null +++ b/docs/integrations/builtin/credentials/cloudflare.md @@ -0,0 +1,9 @@ +# Cloudflare + +You can use these credentials to authenticate the following nodes with Cloudflare: + +* [Cloudflare node](/integrations/builtin/app-nodes/n8n-nodes-base.cloudflare/) + +Follow the [Cloudflare documentation to create an API token](https://developers.cloudflare.com/api/get-started/create-token/){:target=_blank .external-link}. + +Enter your token in the **Cloudflare account** credentials modal. diff --git a/docs/integrations/builtin/credentials/convertKit.md b/docs/integrations/builtin/credentials/convertkit.md similarity index 100% rename from docs/integrations/builtin/credentials/convertKit.md rename to docs/integrations/builtin/credentials/convertkit.md diff --git a/docs/integrations/builtin/credentials/crateDb.md b/docs/integrations/builtin/credentials/cratedb.md similarity index 100% rename from docs/integrations/builtin/credentials/crateDb.md rename to docs/integrations/builtin/credentials/cratedb.md diff --git a/docs/integrations/builtin/credentials/customerIo.md b/docs/integrations/builtin/credentials/customerio.md similarity index 100% rename from docs/integrations/builtin/credentials/customerIo.md rename to docs/integrations/builtin/credentials/customerio.md diff --git a/docs/integrations/builtin/credentials/deepL.md b/docs/integrations/builtin/credentials/deepl.md similarity index 100% rename from docs/integrations/builtin/credentials/deepL.md rename to docs/integrations/builtin/credentials/deepl.md diff --git a/docs/integrations/builtin/credentials/elasticSecurity.md b/docs/integrations/builtin/credentials/elasticsecurity.md similarity index 100% rename from docs/integrations/builtin/credentials/elasticSecurity.md rename to docs/integrations/builtin/credentials/elasticsecurity.md diff --git a/docs/integrations/builtin/credentials/facebookApp.md b/docs/integrations/builtin/credentials/facebookapp.md similarity index 100% rename from docs/integrations/builtin/credentials/facebookApp.md rename to docs/integrations/builtin/credentials/facebookapp.md diff --git a/docs/integrations/builtin/credentials/facebookGraph.md b/docs/integrations/builtin/credentials/facebookgraph.md similarity index 100% rename from docs/integrations/builtin/credentials/facebookGraph.md rename to docs/integrations/builtin/credentials/facebookgraph.md diff --git a/docs/integrations/builtin/credentials/fileMaker.md b/docs/integrations/builtin/credentials/filemaker.md similarity index 100% rename from docs/integrations/builtin/credentials/fileMaker.md rename to docs/integrations/builtin/credentials/filemaker.md diff --git a/docs/integrations/builtin/credentials/formIoTrigger.md b/docs/integrations/builtin/credentials/formiotrigger.md similarity index 100% rename from docs/integrations/builtin/credentials/formIoTrigger.md rename to docs/integrations/builtin/credentials/formiotrigger.md diff --git a/docs/integrations/builtin/credentials/formstackTrigger.md b/docs/integrations/builtin/credentials/formstacktrigger.md similarity index 100% rename from docs/integrations/builtin/credentials/formstackTrigger.md rename to docs/integrations/builtin/credentials/formstacktrigger.md diff --git a/docs/integrations/builtin/credentials/freshworksCrm.md b/docs/integrations/builtin/credentials/freshworkscrm.md similarity index 100% rename from docs/integrations/builtin/credentials/freshworksCrm.md rename to docs/integrations/builtin/credentials/freshworkscrm.md diff --git a/docs/integrations/builtin/credentials/getResponse.md b/docs/integrations/builtin/credentials/getresponse.md similarity index 100% rename from docs/integrations/builtin/credentials/getResponse.md rename to docs/integrations/builtin/credentials/getresponse.md diff --git a/docs/integrations/builtin/credentials/google.md b/docs/integrations/builtin/credentials/google.md deleted file mode 100644 index 726c85a47..000000000 --- a/docs/integrations/builtin/credentials/google.md +++ /dev/null @@ -1,140 +0,0 @@ -# Google - -There are two authentication methods available for Google services nodes, [OAuth2](https://developers.google.com/identity/protocols/oauth2) and the [Service Account](https://developers.google.com/identity/protocols/oauth2#serviceaccount) authentication. Refer to the official Google documentation to learn which is appropriate for your case case. - -Most nodes are [compatible](#compatible-nodes) with OAuth2 authentication. Support for Service Account authentication is limited. - -## Prerequisites - -* [Google Cloud](https://cloud.google.com/){:targe=_blank .external-link} account -* [Google Cloud Platform project](https://developers.google.com/workspace/marketplace/create-gcp-project){:targe=_blank .external-link} -* If using Google Perspective: [Request API Access](https://developers.perspectiveapi.com/s/docs-get-started){:targe=_blank .external-link} -* If using Google Ads: [Developer Token](https://developers.google.com/google-ads/api/docs/first-call/dev-token){:targe=_blank .external-link} - -## Compatible nodes - -Once configured, you can use your credentials to authenticate the following nodes: - -| Node | OAuth | Service Account | -| :--- | :---: | :-------------: | -| [G Suite Admin](/integrations/builtin/app-nodes/n8n-nodes-base.gSuiteAdmin/) | :white_check_mark: | :x: | -| [Google Ads](/integrations/builtin/app-nodes/n8n-nodes-base.googleAds/) | :white_check_mark: | :x: | -| [Gmail](/integrations/builtin/app-nodes/n8n-nodes-base.gmail/) | :white_check_mark: | :white_check_mark: | -| [Google Analytics](/integrations/builtin/app-nodes/n8n-nodes-base.googleAnalytics/) | :white_check_mark: | :x: | -| [Google BigQuery](/integrations/builtin/app-nodes/n8n-nodes-base.googleBigQuery/) | :white_check_mark: | :x: | -| [Google Books](/integrations/builtin/app-nodes/n8n-nodes-base.googleBooks/) | :white_check_mark: | :white_check_mark: | -| [Google Calendar](/integrations/builtin/app-nodes/n8n-nodes-base.googleCalendar/) | :white_check_mark: | :x: | -| [Google Chat](/integrations/builtin/app-nodes/n8n-nodes-base.googleChat/) | :x: | :white_check_mark: | -| [Google Contacts](/integrations/builtin/app-nodes/n8n-nodes-base.googleContacts/) | :white_check_mark: | :x: | -| [Google Cloud Firestore](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudFirestore/) | :white_check_mark: | :x: | -| [Google Cloud Natural Language](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudNaturalLanguage/) | :white_check_mark: | :x: | -| [Google Cloud Realtime Database](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudRealtimeDatabase/) | :white_check_mark: | :x: | -| [Google Docs](/integrations/builtin/app-nodes/n8n-nodes-base.googleDocs/) | :white_check_mark: | :white_check_mark: | -| [Google Drive](/integrations/builtin/app-nodes/n8n-nodes-base.googleDrive/) | :white_check_mark: | :white_check_mark: | -| [Google Drive Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.googleDriveTrigger/) | :white_check_mark: | :white_check_mark: | -| [Google Perspective](/integrations/builtin/app-nodes/n8n-nodes-base.googlePerspective/) | :white_check_mark: | :x: | -| [Google Sheets](/integrations/builtin/app-nodes/n8n-nodes-base.googleSheets/) | :white_check_mark: | :white_check_mark: | -| [Google Slides](/integrations/builtin/app-nodes/n8n-nodes-base.googleSlides/) | :white_check_mark: | :white_check_mark: | -| [Google Tasks](/integrations/builtin/app-nodes/n8n-nodes-base.googleTasks/) | :white_check_mark: | :x: | -| [Google Translate](/integrations/builtin/app-nodes/n8n-nodes-base.googleTranslate/) | :white_check_mark: | :white_check_mark: | -| [YouTube](/integrations/builtin/app-nodes/n8n-nodes-base.youTube/) | :white_check_mark: | :x: | - -!!! note "Note for n8n Cloud users" - For the following nodes, you only need to enter the **Credentials Name** and click on the **Sign in with Google** button in the OAuth section to connect your Google account to n8n: - - * [Google Calendar](/integrations/builtin/app-nodes/n8n-nodes-base.googleCalendar/) - * [Google Contacts](/integrations/builtin/app-nodes/n8n-nodes-base.googleContacts/) - * [Google Sheets](/integrations/builtin/app-nodes/n8n-nodes-base.googleSheets/) - * [Google Tasks](/integrations/builtin/app-nodes/n8n-nodes-base.googleTasks/) - - -## Using OAuth - -From your [Google Cloud Console](https://console.cloud.google.com){:targe=_blank .external-link} dashboard: - -1. Click on the hamburger menu and select **APIs & Services > Credentials**. -2. Click on **+ CREATE CREDENTIALS** and select **OAuth client ID**. - - !!! note "Note for new users" - If you're creating OAuth credentials for the first time, you will have to [configure the consent screen](https://support.google.com/cloud/answer/10311615?hl=en&ref_topic=3473162){:targe=_blank .external-link}. - - -3. From the **Application type** dropdown select **Web application**. A name is automatically generated, change it if desired. -4. From the **Authorized redirect URIs** section, select **+ Add URI**. -5. Enter the **OAuth Callback URL** provided in the Google node credential modal: - ![OAuth Callback URL](/_images/integrations/builtin/credentials/google/oauth_callback.png) -6. Click the **CREATE** button. - -From your n8n instance: - -7. Enter your new **Client ID** and **Client Secret** from Google Cloud Console in the n8n Credentials modal. -8. Enter a **Credentials Name**. -9. Click on the **Sign in with Google** button to complete your Google authentication. -10. **Save** your new credentials in n8n. - -Now you must [enable](#enable-apis) each Google service API that you want to use. - -The following video demonstrates the steps mentioned above. - -
- -
- -## Using Service Account - -From your [Google Cloud Console](https://console.cloud.google.com){:targe=_blank .external-link} dashboard: - -1. Click on the hamburger menu and select **APIs & Services > Credentials**. -2. Click on **+ CREATE CREDENTIALS** and select **Service account**. -3. Enter a name in the **Service account name** field. -4. Click on the **CREATE** button. -5. Based on your use-case, you may want to **Select a role** and **Grant users access to this service account** using the corresponding sections. -6. Click **Done**. -7. Select your newly created service account under the **Service Accounts** section and open the **Keys** tab. -8. Click on **ADD KEY** and select **Create new key**. -9. In the modal that appears, select **JSON** and click **Create**. n8n saves the file to your computer. - -From you n8n instance: - -10. Enter a **Credentials Name**. -11. In the **Service Account Email** field, enter the email associated with your new Service Account (visible in the **Details** tab). -12. Enter the **Private Key** from the downloaded JSON file. If you are running an n8n version older than 0.156.0: replace all instances of `\n` in the JSON file with new lines. -13. Optional: Click the toggle to enable [**Impersonate a User**](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority){:targe=_blank .external-link} and enter the desired email. -14. **Save** your credentials. - -Now you must [enable](#enable-apis) each Google service API that you want to use. - -The following video demonstrates the steps mentioned above. - -
- -
- -## Enable APIs - -To enable an API, follow the steps below: - -1. Access your [Google Cloud Console](https://console.cloud.google.com){:targe=_blank .external-link}. -2. From the hamburger menu select **APIs & Services > Library**. -3. Search for and select the API(s) you want to enable. -5. Click on the **ENABLE** button. - -## Troubleshooting - -### Google hasn't verified this app - -If using the OAuth authentication method, you might come across the warning **Google hasn't verified this app**. To avoid this, you can create OAuth credentials from the same account you want to authenticate. However, if you're using credentials that were generated by another account (by a developer or another third party), do the following: - -1. Click on **Advanced**. -2. Click on **Go to CREDENTIALS_NAME (unsafe)**. `CREDENTIALS_NAME` is the name of the credentials created by the third party. -3. Grant the requested permissions. - -### Service Account cannot access Google Drive files - -A Service Account can only access Google Drive files and folders that were shared with it's associated user email. - -1. Access your [Google Cloud Console](https://console.cloud.google.com){:targe=_blank .external-link} and copy your Service Account email. -2. Access your [Google Drive](https://drive.google.com){:targe=_blank .external-link} and go to the designated file or folder. -3. Right-click on the file or folder and select **Share**. -4. Paste your Service Account email into **Add People and groups**. -5. Select **Editor** for read-write access or **Viewer** for read-only access. diff --git a/docs/integrations/builtin/credentials/google/index.md b/docs/integrations/builtin/credentials/google/index.md new file mode 100644 index 000000000..58f8f6949 --- /dev/null +++ b/docs/integrations/builtin/credentials/google/index.md @@ -0,0 +1,53 @@ +# Google + +This section contains: + +* [OAuth2 single service](/integrations/builtin/credentials/google/oauth-single-service/): create an OAuth2 credential for a specific service node, such as the Gmail node. +* [OAuth2 generic](/integrations/builtin/credentials/google/oauth-generic/): create an OAuth2 credential for use with [custom operations](/integrations/custom-operations/). +* [Service Account](/integrations/builtin/credentials/google/service-account/): create a Service Account credential. + +## OAuth2 and Service Account + +There are two authentication methods available for Google services nodes, [OAuth2](https://developers.google.com/identity/protocols/oauth2){:target=_blank .external-link} and [Service Account](https://cloud.google.com/iam/docs/understanding-service-accounts){:target=_blank .external-link}. n8n recommends using OAuth. It's more widely available, and easier to set up. Refer to the [Google documentation: Understanding service accounts](https://cloud.google.com/iam/docs/understanding-service-accounts){:target=_blank .external-link} for guidance on when you need service account. + +## Compatible nodes + +Once configured, you can use your credentials to authenticate the following nodes. Most nodes are compatible with OAuth2 authentication. Support for Service Account authentication is limited. + +??? Details "Compatibility" + | Node | OAuth | Service Account | + | :--- | :---: | :-------------: | + | [G Suite Admin](/integrations/builtin/app-nodes/n8n-nodes-base.gSuiteAdmin/) | :white_check_mark: | :x: | + | [Google Ads](/integrations/builtin/app-nodes/n8n-nodes-base.googleAds/) | :white_check_mark: | :x: | + | [Gmail](/integrations/builtin/app-nodes/n8n-nodes-base.gmail/) | :white_check_mark: | :white_check_mark: | + | [Google Analytics](/integrations/builtin/app-nodes/n8n-nodes-base.googleAnalytics/) | :white_check_mark: | :x: | + | [Google BigQuery](/integrations/builtin/app-nodes/n8n-nodes-base.googleBigQuery/) | :white_check_mark: | :x: | + | [Google Books](/integrations/builtin/app-nodes/n8n-nodes-base.googleBooks/) | :white_check_mark: | :white_check_mark: | + | [Google Calendar](/integrations/builtin/app-nodes/n8n-nodes-base.googleCalendar/) | :white_check_mark: | :x: | + | [Google Chat](/integrations/builtin/app-nodes/n8n-nodes-base.googleChat/) | :x: | :white_check_mark: | + | [Google Cloud Storage](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudStorage/) | :white_check_mark: | :x: | + | [Google Contacts](/integrations/builtin/app-nodes/n8n-nodes-base.googleContacts/) | :white_check_mark: | :x: | + | [Google Cloud Firestore](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudFirestore/) | :white_check_mark: | :x: | + | [Google Cloud Natural Language](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudNaturalLanguage/) | :white_check_mark: | :x: | + | [Google Cloud Realtime Database](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudRealtimeDatabase/) | :white_check_mark: | :x: | + | [Google Docs](/integrations/builtin/app-nodes/n8n-nodes-base.googleDocs/) | :white_check_mark: | :white_check_mark: | + | [Google Drive](/integrations/builtin/app-nodes/n8n-nodes-base.googleDrive/) | :white_check_mark: | :white_check_mark: | + | [Google Drive Trigger](/integrations/builtin/trigger-nodes/n8n-nodes-base.googleDriveTrigger/) | :white_check_mark: | :white_check_mark: | + | [Google Perspective](/integrations/builtin/app-nodes/n8n-nodes-base.googlePerspective/) | :white_check_mark: | :x: | + | [Google Sheets](/integrations/builtin/app-nodes/n8n-nodes-base.googleSheets/) | :white_check_mark: | :white_check_mark: | + | [Google Slides](/integrations/builtin/app-nodes/n8n-nodes-base.googleSlides/) | :white_check_mark: | :white_check_mark: | + | [Google Tasks](/integrations/builtin/app-nodes/n8n-nodes-base.googleTasks/) | :white_check_mark: | :x: | + | [Google Translate](/integrations/builtin/app-nodes/n8n-nodes-base.googleTranslate/) | :white_check_mark: | :white_check_mark: | + | [YouTube](/integrations/builtin/app-nodes/n8n-nodes-base.youTube/) | :white_check_mark: | :x: | + +!!! note "Note for n8n Cloud users" + For the following nodes, you can authenticate by entering the **Credentials Name** and selecting **Sign in with Google** in the OAuth section to connect your Google account to n8n: + + * [Google Calendar](/integrations/builtin/app-nodes/n8n-nodes-base.googleCalendar/) + * [Google Contacts](/integrations/builtin/app-nodes/n8n-nodes-base.googleContacts/) + * [Google Sheets](/integrations/builtin/app-nodes/n8n-nodes-base.googleSheets/) + * [Google Tasks](/integrations/builtin/app-nodes/n8n-nodes-base.googleTasks/) + + + + diff --git a/docs/integrations/builtin/credentials/google/oauth-generic.md b/docs/integrations/builtin/credentials/google/oauth-generic.md new file mode 100644 index 000000000..214c2d32c --- /dev/null +++ b/docs/integrations/builtin/credentials/google/oauth-generic.md @@ -0,0 +1,97 @@ +# Google: OAuth2 generic + +This document contains instructions for creating a generic OAuth2 Google credential for use with [custom operations](/integrations/custom-operations/). + +## Prerequisites + +* [Google Cloud](https://cloud.google.com/){:targe=_blank .external-link} account +* [Google Cloud Platform project](https://developers.google.com/workspace/marketplace/create-gcp-project){:targe=_blank .external-link} +* If using Google Perspective: [Request API Access](https://developers.perspectiveapi.com/s/docs-get-started){:targe=_blank .external-link} +* If using Google Ads: [Developer Token](https://developers.google.com/google-ads/api/docs/first-call/dev-token){:targe=_blank .external-link} + +## Set up OAuth + +### Create a new credential in n8n + +1. Follow the steps to [Create a credential](/credentials/add-edit-credentials/). If you create a credential by selecting **Create new** in the credentials dropdown in a node, n8n automatically creates the correct credential type for that node. If you select **Credentials > New**, you must browse for the credential type. To create a credential for a [custom API call](/integrations/custom-operations/), select **Google OAuth2 API**. This allows you to create a generic credential, then set its scopes. +2. Note the **OAuth Redirect URL** from the node credential modal. You'll need this in the next section. + + ??? Details "View screenshot" + ![OAuth Callback URL](/_images/integrations/builtin/credentials/google/oauth_callback.png) + +3. You must provide the scopes for this credential. Refer to [Scopes](#scopes) for more information. + +### Set up OAuth in Google Cloud + +1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials){:target=_blank .external-link} and make sure you're in the project you want to use. + + ??? Details "View screenshot" + ![Google project dropdown](/_images/integrations/builtin/credentials/google/check-google-project.png) + +2. Select **+ CREATE CREDENTIALS > OAuth client ID**. If you're creating OAuth credentials for the first time, you must [configure the consent screen](https://support.google.com/cloud/answer/10311615?hl=en&ref_topic=3473162){:target=_blank .external-link}. + + ??? Details "View screenshot" + ![Create credentials](/_images/integrations/builtin/credentials/google/create-credentials.png) + +3. In the **Application type** dropdown, select **Web application**. Google automatically generates a name. +4. Under **Authorizes redirect URIs**, select **+ ADD URI**. Paste in the OAuth redirect URL from the previous step. + + ??? Details "View screenshot" + ![Web application](/_images/integrations/builtin/credentials/google/application-web-application.png) + +5. Select **CREATE**. +6. Enable each Google service API that you want to use: + --8<-- "_snippets/integrations/builtin/credentials/google/enable-apis.md" + +### Create and test your connection + +In n8n: + +1. Enter your new **Client ID** and **Client Secret** from Google Cloud Console in the credentials modal. +2. Select **Sign in with Google** to complete your Google authentication. +3. **Save** your new credentials. + +The following video demonstrates the steps described above: + +
+ +
+ +## Scopes + +Many Google services have multiple possible access scopes. A scope limits what a user can do. Refer to [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes){:target=_blank .external-link} for a list of scopes for all services. + +n8n doesn't support all scopes. When creating a generic Google OAuth2 API credential, you can enter scopes from the list. If you enter a scope that n8n doesn't already support, it won't work. + +??? Details "Supported scopes" + | Service | Available scopes | + | ------- | ---------------- | + | Gmail | https://www.googleapis.com/auth/gmail.labels
https://www.googleapis.com/auth/gmail.addons.current.action.compose
https://www.googleapis.com/auth/gmail.addons.current.message.action
https://mail.google.com/
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.compose | + | Google Ads | https://www.googleapis.com/auth/adwords | + | Google Analytics | https://www.googleapis.com/auth/analytics
https://www.googleapis.com/auth/analytics.readonly | + | Google Big Query | https://www.googleapis.com/auth/bigquery | + | Google Books | https://www.googleapis.com/auth/books | + | Google Calendar | https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events | + | Google Cloud Natural Language | https://www.googleapis.com/auth/cloud-language
https://www.googleapis.com/auth/cloud-platform | + | Google Cloud Storage | https://www.googleapis.com/auth/cloud-platform
https://www.googleapis.com/auth/cloud-platform.read-only
https://www.googleapis.com/auth/devstorage.full_control
https://www.googleapis.com/auth/devstorage.read_only
https://www.googleapis.com/auth/devstorage.read_write | + | Google Contacts | https://www.googleapis.com/auth/contacts | + | Google Docs | https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.file | + | Google Drive | https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.photos.readonly | + | Google Firebase Cloud Firestore | https://www.googleapis.com/auth/datastore
https://www.googleapis.com/auth/firebase | + | Google Firebase Realtime Database | https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/firebase.database
https://www.googleapis.com/auth/firebase | + | Google Perspective | https://www.googleapis.com/auth/userinfo.email | + | Google Sheets | https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/spreadsheets | + | Google Slide | https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/presentations | + | Google Tasks | https://www.googleapis.com/auth/tasks | + | Google Translate | https://www.googleapis.com/auth/cloud-translation | + | GSuite Admin | https://www.googleapis.com/auth/admin.directory.group
https://www.googleapis.com/auth/admin.directory.user
https://www.googleapis.com/auth/admin.directory.domain.readonly
https://www.googleapis.com/auth/admin.directory.userschema.readonly | + +## Troubleshooting + +### Google hasn't verified this app + +If using the OAuth authentication method, you might see the warning **Google hasn't verified this app**. To avoid this, you can create OAuth credentials from the same account you want to authenticate. However, if you're using credentials that were generated by another account (by a developer or another third party), do the following in Google Cloud: + +1. Select**Advanced**. +2. Select **Go to CREDENTIALS_NAME (unsafe)**. `CREDENTIALS_NAME` is the name of the credentials created by the third party. +3. Grant the requested permissions. diff --git a/docs/integrations/builtin/credentials/google/oauth-single-service.md b/docs/integrations/builtin/credentials/google/oauth-single-service.md new file mode 100644 index 000000000..da9d2d5c2 --- /dev/null +++ b/docs/integrations/builtin/credentials/google/oauth-single-service.md @@ -0,0 +1,64 @@ +# Google: OAuth2 single service + +This document contains instructions for creating a Google credential for a single service. They're also available as a video. + +
+ +
+ +!!! note "Note for n8n Cloud users" + For the following nodes, you can authenticate by entering the **Credentials Name** and selecting **Sign in with Google** in the OAuth section to connect your Google account to n8n: + + * [Google Calendar](/integrations/builtin/app-nodes/n8n-nodes-base.googleCalendar/) + * [Google Contacts](/integrations/builtin/app-nodes/n8n-nodes-base.googleContacts/) + * [Google Sheets](/integrations/builtin/app-nodes/n8n-nodes-base.googleSheets/) + * [Google Tasks](/integrations/builtin/app-nodes/n8n-nodes-base.googleTasks/) + + +## Set up OAuth + +You need a [Google Cloud Platform project](https://developers.google.com/workspace/marketplace/create-gcp-project){:targe=_blank .external-link} for these steps. + +1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials){:target=_blank .external-link} and make sure you're in the project you want to use. + + ??? Details "View screenshot" + ![Google project dropdown](/_images/integrations/builtin/credentials/google/check-google-project.png) + +2. Select **+ CREATE CREDENTIALS > OAuth client ID**. If you're creating OAuth credentials for the first time, you must [configure the consent screen](https://support.google.com/cloud/answer/10311615?hl=en&ref_topic=3473162){:target=_blank .external-link}. + + ??? Details "View screenshot" + ![Create credentials](/_images/integrations/builtin/credentials/google/create-credentials.png) + +3. In the **Application type** dropdown, select **Web application**. Google automatically generates a name. + + ??? Details "View screenshot" + ![Web application](/_images/integrations/builtin/credentials/google/application-web-application.png) + +4. Under **Authorizes redirect URIs**, select **+ ADD URI**. Paste in the OAuth redirect URL from the previous step. + + ??? Details "View screenshot" + ![OAuth Callback URL](/_images/integrations/builtin/credentials/google/oauth_callback.png) + ![Add URI](/_images/integrations/builtin/credentials/google/add-uri.png) + +5. Select **CREATE**. +6. Enable each Google service API that you want to use: + + 1. If using Google Perspective or Google Ads: [Request API Access for Perspective](https://developers.perspectiveapi.com/s/docs-get-started){:targe=_blank .external-link} or a [Developer Token for Ads](https://developers.google.com/google-ads/api/docs/first-call/dev-token){:targe=_blank .external-link}. + --8<-- "_snippets/integrations/builtin/credentials/google/enable-apis.md" + +In n8n: + +1. Enter your new **Client ID** and **Client Secret** from Google Cloud Console in the credentials modal. +2. Select **Sign in with Google** to complete your Google authentication. +3. **Save** your new credentials. + + +## Troubleshooting + +### Google hasn't verified this app + +If using the OAuth authentication method, you might see the warning **Google hasn't verified this app**. To avoid this, you can create OAuth credentials from the same account you want to authenticate. However, if you're using credentials that were generated by another account (by a developer or another third party), do the following in Google Cloud: + +1. Select **Advanced**. +2. Select **Go to CREDENTIALS_NAME (unsafe)**. `CREDENTIALS_NAME` is the name of the credentials created by the third party. +3. Grant the requested permissions. diff --git a/docs/integrations/builtin/credentials/google/service-account.md b/docs/integrations/builtin/credentials/google/service-account.md new file mode 100644 index 000000000..aa0102963 --- /dev/null +++ b/docs/integrations/builtin/credentials/google/service-account.md @@ -0,0 +1,82 @@ +# Google: Service Account + +Using service accounts is more complex than OAuth2. Before you begin: + +* Check if your node is [compatible](/integrations/builtin/credentials/google/#compatible-nodes) with Service Account. +* Make sure you need to use service account. For most use cases, OAuth2 is a better option. +* Read the Google documentation on [Creating and managing service accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts){:target=_blank .external-link}. + + +## Prerequisites + +* [Google Cloud](https://cloud.google.com/){:targe=_blank .external-link} account +* [Google Cloud Platform project](https://developers.google.com/workspace/marketplace/create-gcp-project){:targe=_blank .external-link} + +## Set up Service Account + +### Create a new credential in n8n + +1. Follow the steps to [Create a credential](/credentials/add-edit-credentials/). + + !!! note "Generic and specific credentials" + If you create a credential by selecting **Create new** in the credentials dropdown in a node, n8n automatically creates the correct credential type for that node. If you select **Credentials > New**, you must browse for the credential type: + + * To connect with a specific service, using resources and operations supported by n8n, choose that service. For example, to create a credential for use in the Gmail node, search for `Gmail`. + * To create a credential for a [custom API call](/integrations/custom-operations/), select **Google API**. + +2. Note the **Private Key** from the node credential modal. You'll need this in the next section. + +### Set up service account in Google Cloud + +In your [Google Cloud Console](https://console.cloud.google.com){:target=_blank .external-link} dashboard: + +1. Select the hamburger menu **> APIs & Services > Credentials**. Google takes you to your **Credentials** page. + + ??? Details "View screenshot" + ![Access the Credentials page for APIs and services](/_images/integrations/builtin/credentials/google/service-account-api-services-credentials.png) + +2. Select **+ CREATE CREDENTIALS > Service account**. + + ??? Details "View screenshot" + ![Access the Credentials page for APIs and services](/_images/integrations/builtin/credentials/google/service-account-create-credentials.png) + +3. Enter a name in **Service account name**, and an ID in **Service account ID**. Refer to [Creating a service account](https://cloud.google.com/iam/docs/creating-managing-service-accounts?hl=en#creating){:target=_blank .external-link} for more information. +4. Select **CREATE AND CONTINUE**. +5. Based on your use-case, you may want to **Select a role** and **Grant users access to this service account** using the corresponding sections. +6. Select **DONE**. +7. Select your newly created service account under the **Service Accounts** section. Open the **KEYS** tab. +8. Select **ADD KEY > Create new key**. + + ??? Details "View screenshot" + ![Create a new key](/_images/integrations/builtin/credentials/google/service-account-create-key.png) + +9. In the modal that appears, select **JSON**, then select **CREATE**. Google saves the file to your computer. +10. Enable each Google service API that you want to use: + --8<-- "_snippets/integrations/builtin/credentials/google/enable-apis.md" + +### Create and test your connection + +In n8n: + +1. In the **Service Account Email** field, enter the email associated with your new Service Account (you can find this in the **Details** tab in Google Cloud). +2. Enter the **Private Key** from the downloaded JSON file. If you're running an n8n version older than 0.156.0: replace all instances of `\n` in the JSON file with new lines. +3. **Optional**: Click the toggle to enable [**Impersonate a User**](https://developers.google.com/identity/protocols/oauth2/service-account#delegatingauthority){:target=_blank .external-link} and enter the email. +4. **Save** your credentials. + +The following video demonstrates the steps described above. + +
+ +
+ +## Troubleshooting + +### Service Account cannot access Google Drive files + +A Service Account can't access Google Drive files and folders that weren't shared with its associated user email. + +1. Access your [Google Cloud Console](https://console.cloud.google.com){:target=_blank .external-link} and copy your Service Account email. +2. Access your [Google Drive](https://drive.google.com){:target=_blank .external-link} and go to the designated file or folder. +3. Right-click on the file or folder and select **Share**. +4. Paste your Service Account email into **Add People and groups**. +5. Select **Editor** for read-write access or **Viewer** for read-only access. diff --git a/docs/integrations/builtin/credentials/goToWebinar.md b/docs/integrations/builtin/credentials/gotowebinar.md similarity index 100% rename from docs/integrations/builtin/credentials/goToWebinar.md rename to docs/integrations/builtin/credentials/gotowebinar.md diff --git a/docs/integrations/builtin/credentials/haloPSA.md b/docs/integrations/builtin/credentials/halopsa.md similarity index 100% rename from docs/integrations/builtin/credentials/haloPSA.md rename to docs/integrations/builtin/credentials/halopsa.md diff --git a/docs/integrations/builtin/credentials/helpScout.md b/docs/integrations/builtin/credentials/helpscout.md similarity index 100% rename from docs/integrations/builtin/credentials/helpScout.md rename to docs/integrations/builtin/credentials/helpscout.md diff --git a/docs/integrations/builtin/credentials/highLevel.md b/docs/integrations/builtin/credentials/highlevel.md similarity index 100% rename from docs/integrations/builtin/credentials/highLevel.md rename to docs/integrations/builtin/credentials/highlevel.md diff --git a/docs/integrations/builtin/credentials/homeAssistant.md b/docs/integrations/builtin/credentials/homeassistant.md similarity index 100% rename from docs/integrations/builtin/credentials/homeAssistant.md rename to docs/integrations/builtin/credentials/homeassistant.md diff --git a/docs/integrations/builtin/credentials/httpRequest.md b/docs/integrations/builtin/credentials/httpRequest.md deleted file mode 100644 index 2f3e5efae..000000000 --- a/docs/integrations/builtin/credentials/httpRequest.md +++ /dev/null @@ -1,77 +0,0 @@ -# HTTP Request - -You can use these credentials to authenticate the following nodes: - -- [HTTP Request](/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest/) - -## Prerequisites - -You must use the authentication method required by the app or service you want to query. - -### Existing credential types - -n8n recommends using this option whenever there's a credential type available for the service you want to connect to. It offers an easier way to set up and manage credentials, compared to configuring generic credentials. - -You can use [Predefined credential types](/integrations/custom-operations/#predefined-credential-types) to perform custom operations with some APIs where n8n has a node for the platform. For example, n8n has an Asana node, and supports using your Asana credentials in the HTTP Request node. Refer to [Custom operations](/integrations/custom-operations/) for more information. - -### Generic authentication - -The following generic authentication methods are available: - -* Basic Auth -* Digest Auth -* Header Auth -* OAuth1 -* OAuth2 -* None - -You can learn more about HTTP authentication [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#see_also). - - -## Using an existing credential type - ---8<-- "_snippets/integrations/predefined-credential-type-how-to.md" - -Refer to [Custom API operations](/integrations/custom-operations/) for more information. - -## Using Basic Auth / Digest Auth - -1. Enter a descriptive *Credentials Name*. -2. In the *Credential Data* section, enter the *Username* and *Password* for the app or service your HTTP Request is targeting. -3. Click **Create** to save your credentials. - -## Using Header Auth - -1. Enter a descriptive *Credentials Name*. -2. In the *Credential Data* section, enter the header *Name* and *Value* required for the app or service your HTTP Request is targeting. Read more about [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#authentication). -3. Click **Create** to save your credentials. - -## Using OAuth1 - -1. Enter a descriptive *Credentials Name*. -2. In the *Credential Data* section, enter the following authentication details: - * *Authorization URL* - * *Access Token URL* - * *Consumer Key* - * *Consumer Secret* - * *Request Token URL* - * *Signature Method* -3. Click **Create** to save your credentials. - -Read more about [OAuth1](https://oauth.net/1/). - -## Using OAuth2 - -1. Enter a descriptive *Credentials Name*. -2. In the *Credential Data* section, enter the following authentication details: - * *Authorization URL* - * *Access Token URL* - * *Client ID* - * *Client Secret* - * *Scope* - * *Auth URI Query Parameters* - * *Authentication* -3. Click **Create** to save your credentials. - -Read more about [OAuth2](https://oauth.net/2/). - diff --git a/docs/integrations/builtin/credentials/httprequest.md b/docs/integrations/builtin/credentials/httprequest.md new file mode 100644 index 000000000..8274cce8f --- /dev/null +++ b/docs/integrations/builtin/credentials/httprequest.md @@ -0,0 +1,77 @@ +# HTTP Request + +You can use these credentials to authenticate the following nodes: + +- [HTTP Request](/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest/) + +## Prerequisites + +You must use the authentication method required by the app or service you want to query. + +### Existing credential types + +n8n recommends using this option whenever there's a credential type available for the service you want to connect to. It offers an easier way to set up and manage credentials, compared to configuring generic credentials. + +You can use [Predefined credential types](/integrations/custom-operations/#predefined-credential-types) to perform custom operations with some APIs where n8n has a node for the platform. For example, n8n has an Asana node, and supports using your Asana credentials in the HTTP Request node. Refer to [Custom operations](/integrations/custom-operations/) for more information. + +### Generic authentication + +The following generic authentication methods are available: + +* Basic Auth +* Digest Auth +* Header Auth +* OAuth1 +* OAuth2 +* None + +You can learn more about HTTP authentication [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#see_also){:target=_blank .external-link}. + + +## Using an existing credential type + +--8<-- "_snippets/integrations/predefined-credential-type-how-to.md" + +Refer to [Custom API operations](/integrations/custom-operations/) for more information. + +## Using Basic Auth or Digest Auth + +1. Update the credential name. +2. Enter the **Username** and **Password** for the app or service your HTTP Request is targeting. +3. Select **Save** to save your credentials. + +## Using Header Auth + +1. Update the credential name. +2. Enter the header **Name** and **Value** required for the app or service your HTTP Request is targeting. Read more about [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers#authentication){:target=_blank .external-link}. +3. Select **Save** to save your credentials. + +## Using OAuth1 + +1. Update the credential name. +2. Enter the following authentication details: + * **Authorization URL** + * **Access Token URL** + * **Consumer Key** + * **Consumer Secret** + * **Request Token URL** + * **Signature Method** +3. Select **Save** to save your credentials. + +Read more about [OAuth1](https://oauth.net/1/){:target=_blank .external-link}. + +## Using OAuth2 + +1. Update the credential name. +2. Enter the following authentication details: + * **Authorization URL** + * **Access Token URL** + * **Client ID** + * **Client Secret** + * **Scope** + * **Auth URI Query Parameters** + * **Authentication** +3. Select **Save** to save your credentials. + +Read more about [OAuth2](https://oauth.net/2/){:target=_blank .external-link}. + diff --git a/docs/integrations/builtin/credentials/humanticAi.md b/docs/integrations/builtin/credentials/humanticai.md similarity index 100% rename from docs/integrations/builtin/credentials/humanticAi.md rename to docs/integrations/builtin/credentials/humanticai.md diff --git a/docs/integrations/builtin/credentials/imap.md b/docs/integrations/builtin/credentials/imap.md index 34fbfd0af..9d5703817 100644 --- a/docs/integrations/builtin/credentials/imap.md +++ b/docs/integrations/builtin/credentials/imap.md @@ -2,7 +2,7 @@ You can use these credentials to authenticate the following nodes with IMAP. -- [IMAP Email](/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/) +- [IMAP Email](/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/) ## Prerequisites diff --git a/docs/integrations/builtin/credentials/index.md b/docs/integrations/builtin/credentials/index.md index fd103a70e..0bf70430a 100644 --- a/docs/integrations/builtin/credentials/index.md +++ b/docs/integrations/builtin/credentials/index.md @@ -1,4 +1,6 @@ -# Overview +# Credentials library This section contains step-by-step information about authenticating the different nodes in n8n. +To learn more about creating, managing, and sharing credentials, refer to [Manage credentials](/credentials/). + diff --git a/docs/integrations/builtin/credentials/invoiceNinja.md b/docs/integrations/builtin/credentials/invoiceninja.md similarity index 100% rename from docs/integrations/builtin/credentials/invoiceNinja.md rename to docs/integrations/builtin/credentials/invoiceninja.md diff --git a/docs/integrations/builtin/credentials/jotForm.md b/docs/integrations/builtin/credentials/jotform.md similarity index 100% rename from docs/integrations/builtin/credentials/jotForm.md rename to docs/integrations/builtin/credentials/jotform.md diff --git a/docs/integrations/builtin/credentials/lingvaNex.md b/docs/integrations/builtin/credentials/lingvanex.md similarity index 100% rename from docs/integrations/builtin/credentials/lingvaNex.md rename to docs/integrations/builtin/credentials/lingvanex.md diff --git a/docs/integrations/builtin/credentials/linkedIn.md b/docs/integrations/builtin/credentials/linkedin.md similarity index 100% rename from docs/integrations/builtin/credentials/linkedIn.md rename to docs/integrations/builtin/credentials/linkedin.md diff --git a/docs/integrations/builtin/credentials/mailerLite.md b/docs/integrations/builtin/credentials/mailerlite.md similarity index 100% rename from docs/integrations/builtin/credentials/mailerLite.md rename to docs/integrations/builtin/credentials/mailerlite.md diff --git a/docs/integrations/builtin/credentials/messageBird.md b/docs/integrations/builtin/credentials/messagebird.md similarity index 100% rename from docs/integrations/builtin/credentials/messageBird.md rename to docs/integrations/builtin/credentials/messagebird.md diff --git a/docs/integrations/builtin/credentials/microsoftSql.md b/docs/integrations/builtin/credentials/microsoftsql.md similarity index 100% rename from docs/integrations/builtin/credentials/microsoftSql.md rename to docs/integrations/builtin/credentials/microsoftsql.md diff --git a/docs/integrations/builtin/credentials/mondayCom.md b/docs/integrations/builtin/credentials/mondaycom.md similarity index 100% rename from docs/integrations/builtin/credentials/mondayCom.md rename to docs/integrations/builtin/credentials/mondaycom.md diff --git a/docs/integrations/builtin/credentials/mongoDb.md b/docs/integrations/builtin/credentials/mongodb.md similarity index 100% rename from docs/integrations/builtin/credentials/mongoDb.md rename to docs/integrations/builtin/credentials/mongodb.md diff --git a/docs/integrations/builtin/credentials/monicaCrm.md b/docs/integrations/builtin/credentials/monicacrm.md similarity index 100% rename from docs/integrations/builtin/credentials/monicaCrm.md rename to docs/integrations/builtin/credentials/monicacrm.md diff --git a/docs/integrations/builtin/credentials/mySql.md b/docs/integrations/builtin/credentials/mysql.md similarity index 100% rename from docs/integrations/builtin/credentials/mySql.md rename to docs/integrations/builtin/credentials/mysql.md diff --git a/docs/integrations/builtin/credentials/nextCloud.md b/docs/integrations/builtin/credentials/nextcloud.md similarity index 100% rename from docs/integrations/builtin/credentials/nextCloud.md rename to docs/integrations/builtin/credentials/nextcloud.md diff --git a/docs/integrations/builtin/credentials/nocoDb.md b/docs/integrations/builtin/credentials/nocodb.md similarity index 100% rename from docs/integrations/builtin/credentials/nocoDb.md rename to docs/integrations/builtin/credentials/nocodb.md diff --git a/docs/integrations/builtin/credentials/oneSimpleApi.md b/docs/integrations/builtin/credentials/onesimpleapi.md similarity index 100% rename from docs/integrations/builtin/credentials/oneSimpleApi.md rename to docs/integrations/builtin/credentials/onesimpleapi.md diff --git a/docs/integrations/builtin/credentials/openWeatherMap.md b/docs/integrations/builtin/credentials/openweathermap.md similarity index 100% rename from docs/integrations/builtin/credentials/openWeatherMap.md rename to docs/integrations/builtin/credentials/openweathermap.md diff --git a/docs/integrations/builtin/credentials/pagerDuty.md b/docs/integrations/builtin/credentials/pagerduty.md similarity index 100% rename from docs/integrations/builtin/credentials/pagerDuty.md rename to docs/integrations/builtin/credentials/pagerduty.md diff --git a/docs/integrations/builtin/credentials/payPal.md b/docs/integrations/builtin/credentials/paypal.md similarity index 100% rename from docs/integrations/builtin/credentials/payPal.md rename to docs/integrations/builtin/credentials/paypal.md diff --git a/docs/integrations/builtin/credentials/philipsHue.md b/docs/integrations/builtin/credentials/philipshue.md similarity index 100% rename from docs/integrations/builtin/credentials/philipsHue.md rename to docs/integrations/builtin/credentials/philipshue.md diff --git a/docs/integrations/builtin/credentials/postHog.md b/docs/integrations/builtin/credentials/posthog.md similarity index 100% rename from docs/integrations/builtin/credentials/postHog.md rename to docs/integrations/builtin/credentials/posthog.md diff --git a/docs/integrations/builtin/credentials/profitWell.md b/docs/integrations/builtin/credentials/profitwell.md similarity index 100% rename from docs/integrations/builtin/credentials/profitWell.md rename to docs/integrations/builtin/credentials/profitwell.md diff --git a/docs/integrations/builtin/credentials/questDb.md b/docs/integrations/builtin/credentials/questdb.md similarity index 100% rename from docs/integrations/builtin/credentials/questDb.md rename to docs/integrations/builtin/credentials/questdb.md diff --git a/docs/integrations/builtin/credentials/seaTable.md b/docs/integrations/builtin/credentials/seatable.md similarity index 100% rename from docs/integrations/builtin/credentials/seaTable.md rename to docs/integrations/builtin/credentials/seatable.md diff --git a/docs/integrations/builtin/credentials/securityScorecard.md b/docs/integrations/builtin/credentials/securityscorecard.md similarity index 100% rename from docs/integrations/builtin/credentials/securityScorecard.md rename to docs/integrations/builtin/credentials/securityscorecard.md diff --git a/docs/integrations/builtin/credentials/sendEmail.md b/docs/integrations/builtin/credentials/sendemail.md similarity index 100% rename from docs/integrations/builtin/credentials/sendEmail.md rename to docs/integrations/builtin/credentials/sendemail.md diff --git a/docs/integrations/builtin/credentials/sendInBlue.md b/docs/integrations/builtin/credentials/sendinblue.md similarity index 100% rename from docs/integrations/builtin/credentials/sendInBlue.md rename to docs/integrations/builtin/credentials/sendinblue.md diff --git a/docs/integrations/builtin/credentials/sentryIo.md b/docs/integrations/builtin/credentials/sentryio.md similarity index 100% rename from docs/integrations/builtin/credentials/sentryIo.md rename to docs/integrations/builtin/credentials/sentryio.md diff --git a/docs/integrations/builtin/credentials/serviceNow.md b/docs/integrations/builtin/credentials/servicenow.md similarity index 100% rename from docs/integrations/builtin/credentials/serviceNow.md rename to docs/integrations/builtin/credentials/servicenow.md diff --git a/docs/integrations/builtin/credentials/surveyMonkey.md b/docs/integrations/builtin/credentials/surveymonkey.md similarity index 100% rename from docs/integrations/builtin/credentials/surveyMonkey.md rename to docs/integrations/builtin/credentials/surveymonkey.md diff --git a/docs/integrations/builtin/credentials/syncroMsp.md b/docs/integrations/builtin/credentials/syncromsp.md similarity index 100% rename from docs/integrations/builtin/credentials/syncroMsp.md rename to docs/integrations/builtin/credentials/syncromsp.md diff --git a/docs/integrations/builtin/credentials/theHive.md b/docs/integrations/builtin/credentials/thehive.md similarity index 100% rename from docs/integrations/builtin/credentials/theHive.md rename to docs/integrations/builtin/credentials/thehive.md diff --git a/docs/integrations/builtin/credentials/timescaleDb.md b/docs/integrations/builtin/credentials/timescaledb.md similarity index 100% rename from docs/integrations/builtin/credentials/timescaleDb.md rename to docs/integrations/builtin/credentials/timescaledb.md diff --git a/docs/integrations/builtin/credentials/travisCi.md b/docs/integrations/builtin/credentials/travisci.md similarity index 100% rename from docs/integrations/builtin/credentials/travisCi.md rename to docs/integrations/builtin/credentials/travisci.md diff --git a/docs/integrations/builtin/credentials/unleashedSoftware.md b/docs/integrations/builtin/credentials/unleashedsoftware.md similarity index 100% rename from docs/integrations/builtin/credentials/unleashedSoftware.md rename to docs/integrations/builtin/credentials/unleashedsoftware.md diff --git a/docs/integrations/builtin/credentials/uProc.md b/docs/integrations/builtin/credentials/uproc.md similarity index 100% rename from docs/integrations/builtin/credentials/uProc.md rename to docs/integrations/builtin/credentials/uproc.md diff --git a/docs/integrations/builtin/credentials/uptimeRobot.md b/docs/integrations/builtin/credentials/uptimerobot.md similarity index 100% rename from docs/integrations/builtin/credentials/uptimeRobot.md rename to docs/integrations/builtin/credentials/uptimerobot.md diff --git a/docs/integrations/builtin/credentials/urlScanIo.md b/docs/integrations/builtin/credentials/urlscanio.md similarity index 100% rename from docs/integrations/builtin/credentials/urlScanIo.md rename to docs/integrations/builtin/credentials/urlscanio.md diff --git a/docs/integrations/builtin/credentials/venafitlsprotectcloud.md b/docs/integrations/builtin/credentials/venafitlsprotectcloud.md new file mode 100644 index 000000000..b38ed59d1 --- /dev/null +++ b/docs/integrations/builtin/credentials/venafitlsprotectcloud.md @@ -0,0 +1,11 @@ +# Venafi TLS Protect Cloud + +You can use these credentials to authenticate the following nodes with Venafi TLS Protect Cloud: + +* [Venafi TLS Protect Cloud node](/integrations/builtin/app-nodes/n8n-nodes-base.venafiTlsProtectCloud/) +* [Venafi TLS Protect Cloud trigger node](/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectcloudtrigger/) + + +Follow the Venafi REST API documentation on [Obtaining an API Key](https://docs.venafi.cloud/api/obtaining-api-key/){:target=_blank .external-link}. + +Enter the API key in the **Venafi TLS Protect Cloud account** credentials modal. Refer to [Add and edit credentials](/credentials/add-edit-credentials/) for more information on working with credentials in n8n. diff --git a/docs/integrations/builtin/credentials/venafitlsprotectdatacenter.md b/docs/integrations/builtin/credentials/venafitlsprotectdatacenter.md new file mode 100644 index 000000000..767a3aede --- /dev/null +++ b/docs/integrations/builtin/credentials/venafitlsprotectdatacenter.md @@ -0,0 +1,10 @@ +# Venafi TLS Protect Datacenter + +You can use these credentials to authenticate the following nodes with Venafi TLS Protect Datacenter: + +* [Venafi TLS Protect Datacenter node](/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectdatacenter/) +* [Venafi TLS Protect Datacenter trigger node](/integrations/builtin/app-nodes/n8n-nodes-base.venafitlsprotectdatacentertrigger/) + +Venafi provide a [PDF guide](/_downloads/venafi-tpp.pdf) to getting credentials. Follow the steps in the guide, making a note of the name and client ID you choose. When choosing scopes, make sure you choose the scopes needed for the operations you want to perform within n8n. For example, if you plan to work with certificates, including deleting them, include the **Certificate** scope in your Venafi credentials setup, with the **delete** option enabled. + +Enter the client ID, your username and password, and your Venafi domain, in the n8n **Venafi TLS Protect Datacenter account** modal. Refer to [Add and edit credentials](/credentials/add-edit-credentials/) for more information on working with credentials in n8n. diff --git a/docs/integrations/builtin/credentials/whatsapp.md b/docs/integrations/builtin/credentials/whatsapp.md new file mode 100644 index 000000000..d138ee4e9 --- /dev/null +++ b/docs/integrations/builtin/credentials/whatsapp.md @@ -0,0 +1,8 @@ +# WhatsApp Business + +You can use these credentials to authenticate with the [WhatsApp](/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp/) node. + +Refer to the [WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/){:target=_blank .external-link} to get your access token and business account ID. + + + diff --git a/docs/integrations/builtin/credentials/wooCommerce.md b/docs/integrations/builtin/credentials/woocommerce.md similarity index 100% rename from docs/integrations/builtin/credentials/wooCommerce.md rename to docs/integrations/builtin/credentials/woocommerce.md diff --git a/docs/integrations/builtin/index.md b/docs/integrations/builtin/index.md index eb99a2fe7..2e0fc94c2 100644 --- a/docs/integrations/builtin/index.md +++ b/docs/integrations/builtin/index.md @@ -1,4 +1,4 @@ -# Overview +# Built-in integrations This section contains the node library: reference documentation for every built-in node in n8n, and their credentials. @@ -24,4 +24,6 @@ External services need a way to identify and authenticate users. This data can r Nodes in n8n can then request that credential information. As another layer of security, only node types with specific access rights can access the credentials. -To make sure that the data is secure, it gets saved to the database encrypted. n8n uses a random personal encryption key, which it automatically generates on the first run of n8n and then saved under `~/.n8n/config`. \ No newline at end of file +To make sure that the data is secure, it gets saved to the database encrypted. n8n uses a random personal encryption key, which it automatically generates on the first run of n8n and then saved under `~/.n8n/config`. + +To learn more about creating, managing, and sharing credentials, refer to [Manage credentials](/credentials/). diff --git a/docs/integrations/builtin/trigger-nodes/index.md b/docs/integrations/builtin/trigger-nodes/index.md index ab65777ce..4b6301180 100644 --- a/docs/integrations/builtin/trigger-nodes/index.md +++ b/docs/integrations/builtin/trigger-nodes/index.md @@ -1,3 +1,3 @@ -# Overview +# Trigger nodes library -This section provides information about n8n's trigger nodes. \ No newline at end of file +This section provides information about n8n's trigger nodes. diff --git a/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.gmailTrigger.md b/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.gmailTrigger.md new file mode 100644 index 000000000..226400bb0 --- /dev/null +++ b/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.gmailTrigger.md @@ -0,0 +1,14 @@ +# Gmail Trigger + +[Gmail](https://www.gmail.com) is an email service developed by Google. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/google/). + +## Events + +* Message Received + +## Related resources + +n8n provides an app node for Gmail. You can find the node docs [here](/integrations/builtin/app-nodes/n8n-nodes-base.gmail/). diff --git a/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectcloudtrigger.md b/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectcloudtrigger.md new file mode 100644 index 000000000..3e2ad7fed --- /dev/null +++ b/docs/integrations/builtin/trigger-nodes/n8n-nodes-base.venafitlsprotectcloudtrigger.md @@ -0,0 +1,8 @@ +# Venafi TLS Protect Cloud Trigger + +[Venafi](https://www.venafi.com/){:target=_blank .external-link} is a cybersecurity company providing services for machine identity management. They offer solutions to manage and protect identities for a wide range of machine types, delivering global visibility, lifecycle automation, and actionable intelligence. + +The n8n Venafi TLS Protect Cloud trigger node allows you to start a workflow in n8n in response to events in the [cloud-based Venafi TLS Protect](https://vaas.venafi.com/){:target=_blank} service. + +!!! note "Credentials" + You can find authentication information for this node [here](/integrations/builtin/credentials/venafiTlsProtectCloud/). diff --git a/docs/integrations/community-nodes/index.md b/docs/integrations/community-nodes/index.md index 2ebe8d743..38f1c4c7b 100644 --- a/docs/integrations/community-nodes/index.md +++ b/docs/integrations/community-nodes/index.md @@ -1,4 +1,4 @@ -# Overview +# Community nodes n8n provides hundreds of built-in nodes. It also supports users [creating their own nodes](/integrations/creating-nodes/). These are community nodes. diff --git a/docs/integrations/creating-nodes/archive/programmatic-partial.md b/docs/integrations/creating-nodes/archive/programmatic-partial.md deleted file mode 100644 index 2c136c8d3..000000000 --- a/docs/integrations/creating-nodes/archive/programmatic-partial.md +++ /dev/null @@ -1,646 +0,0 @@ -# Tutorial: Build a programmatic-style node - -This tutorial walks through building a programmatic-style node. Before you begin, make sure this is the node style you need. Refer to [Choose your node building approach](/integrations/creating-nodes/plan/choose-node-method/) for more information. - -## Prerequisites - -You need the following installed on your development machine: - ---8<-- "_snippets/integrations/creating-nodes/prerequisites.md" - -You need some understanding of: - -- JavaScript/TypeScript -- REST APIs -- git -- Expressions in n8n - - -## Build your node - -In this section, you'll clone n8n's node starter repository, and build a node that integrates the [SendGrid](https://sendgrid.com/){:target=_blank .external-link}. You'll create a node that implements one piece of SendGrid functionality: create a contact. - -!!! note "Existing node" - n8n has a built-in SendGrid node. To avoid clashing with the existing node, you'll give your version a different name. - -### Step 1: Set up the project - ---8<-- "_snippets/integrations/creating-nodes/tutorial-set-up-project.md" - -Now create the following directories and files: - -* `nodes/FriendGrid` -* `nodes/FriendGrid/FriendGrid.node.json` -* `nodes/FriendGrid/FriendGrid.node.ts` -* `nodes/FriendGrid/friendgrid.svg` -* `credentials/FriendGridApi.credentials.ts` - -These are the key files required for any node. Refer to [Node file structure](/integrations/creating-nodes/build/reference/node-file-structure/) for more information on required files and recommended organization. - -Now install the project dependencies: - -```shell -npm i -``` - -### Step 2: Add an icon - -Copy and paste the SendGrid SVG logo from [here](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/SendGrid/sendGrid.svg){:target=_blank .external-link} into `sendgrid.svg`. To get the SVG source, select **Raw**. - - ---8<-- "_snippets/integrations/creating-nodes/node-icons.md" - - -### Step 3: Update the npm package details - -Your npm package details are in the `package.json` at the root of the project. It's essential to include the `n8n` object with links to the credentials and base node file. Update this file to include the following information: - -```json -{ - // All node names must start with "n8n-nodes-" - "name": "n8n-nodes-friendgrid", - "version": "0.1.0", - "description": "n8n node to create contacts in SendGrid", - "keywords": [ - // This keyword is required for community nodes - "n8n-community-node-package" - ], - "license": "MIT", - "homepage": "https://n8n.io", - "author": { - "name": "Test", - "email": "test@example.com" - }, - "repository": { - "type": "git", - // Change the git remote to your own repository - // Add the new URL here - "url": "git+" - }, - "main": "index.js", - "scripts": { - // don't change - }, - "files": [ - "dist" - ], - // Link the credentials and node - "n8n": { - "credentials": [ - "dist/credentials/FriendGridApi.credentials.js" - ], - "nodes": [ - "dist/nodes/FriendGrid/.node.js" - ] - }, - "devDependencies": { - // don't change - }, - "dependencies": { - // don't change - } -} -``` - -### Step 4: Add node metadata - -Metadata about your node goes in the JSON file at the root of your node. n8n refers to this as the codex file. In this example, the file is `FriendGrid.node.json`. - -Add the following code to the JSON file: - -```json -{ - "node": "n8n-nodes-base.FriendGrid", - "nodeVersion": "1.0", - "codexVersion": "1.0", - "categories": [ - "Miscellaneous" - ], - "resources": { - "credentialDocumentation": [ - { - "url": "" - } - ], - "primaryDocumentation": [ - { - "url": "" - } - ] - } -} -``` - -For more information on these parameters, refer to [Node codex files](/integrations/creating-nodes/build/reference/node-codex-files/). - -### Step 5: Create the node - -Every node must have a base file. In this example, the file is `FriendGrid.node.ts`. To keep this tutorial short, you'll place all the node functionality in this one file. When building more complex nodes, you should consider splitting out your functionality into modules. Refer to [Node file structure](/integrations/creating-nodes/build/reference/node-file-structure/) for more information. - -#### Step 5.1: Imports - -Start by adding the import statements: - -```typescript -import { - IExecuteFunctions, -} from 'n8n-core'; - -import { - IDataObject, - INodeExecutionData, - INodeType, - INodeTypeDescription, -} from 'n8n-workflow'; - -import { - OptionsWithUri, -} from 'request'; -``` - -#### Step 5.2: Create the main class - -The node must export an interface that implements `INodeType`. This interface must include a `description` interface, which in turn contains the `properties` array. - -!!! note "Class names and file names" - Make sure the class name and the file name match. For example, given a class `FriendGrid`, the filename must be `FriendGrid.node.ts`. - -```typescript -export class FriendGrid implements INodeType { - description: INodeTypeDescription = { - // Basic node details will go here - properties: [ - // Resources and operations will go here - ] - }; -} -``` - -#### Step 5.3: Add node details - -All programmatic nodes need some basic parameters, such as their display name and icon. Add the following to the `description`: - -```typescript -displayName: 'FriendGrid', -name: 'friendGrid', -icon: 'file:friendGrid.svg', -group: ['transform'], -version: 1, -description: 'Consume SendGrid API', -defaults: { - name: 'FriendGrid' -}, -inputs: ['main'], -outputs: ['main'], -credentials: [ - { - name: 'friendGridApi', - required: true, - }, -], -``` - - - - - - - - - -## Creating the UI for the node - -Double-clicking on the FriendGrid node will open the Node Editor View. It will be empty since we haven't added any UI components yet. Luckily, n8n provides predefined JSON-based UI components that we can use to ask the user for different types of data. - -SendGrid's [docs](https://sendgrid.com/docs/api-reference/) mention that to create a contact, we need to provide the following pieces of information: - -- email - Required -- first_name - Optional -- last_name - Optional - -There are more parameters that can be provided to create a contact in FriendGrid, but we will use only these three in this tutorial. - -### Resources and operations - -Now, n8n requires a couple of parameters as well: - -- resource - Required -- operation - Required - -You can get the node to work without these two parameters, but these should be added for the sake of consistency with the other nodes. Resources and Operations help in organizing all the functionalities of a node. These ensure that all the functionalities of a node remain easily discoverable as the node grows. - -- The resource value is always singular and its value is the name of the API resource that we want to use. Since we are working with contacts, the resource value would be `contact`. -- The operation value is always singular as well and it is the name of the operation to perform over the resource. Since we are creating contacts, the operation value would be `create`. - -You might say that you can “Add a contact” and you are right, but we try to use the same operations (create, delete, get, getAll and update) across all the nodes. - -### Adding required fields - -Let’s make the Node Editor View ask for these parameters: - -1. Add the following under `description.properties` in `packages/nodes-base/nodes/FriendGrid/FriendGrid.node.ts`. - -```typescript -{ - displayName: 'Resource', - name: 'resource', - type: 'options', - options: [ - { - name: 'Contact', - value: 'contact', - }, - ], - default: 'contact', - required: true, - description: 'Resource to consume', -}, -{ - displayName: 'Operation', - name: 'operation', - type: 'options', - displayOptions: { - show: { - resource: [ - 'contact', - ], - }, - }, - options: [ - { - name: 'Create', - value: 'create', - description: 'Create a contact', - }, - ], - default: 'create', - description: 'The operation to perform.', -}, -{ - displayName: 'Email', - name: 'email', - type: 'string', - required: true, - displayOptions: { - show: { - operation: [ - 'create', - ], - resource: [ - 'contact', - ], - }, - }, - default:'', - description:'Primary email for the contact', -}, -``` - -2. Stop the current n8n process by pressing ctrl + c in the terminal in which you are running n8n. -3. Run again, by entering the following in the terminal. - ```bash - npm run dev - ``` -4. Go to [localhost:8080](http://localhost:8080/), refresh the page, and open the node again. - -The node should now look like in the following image. - -![FriendGrid's required fields](/_images/integrations/creating-nodes/friendgrid-required-fields.png) - -### Adding optional fields - -We have given the node the possibility to ask for all the required parameters needed to create a contact. But, what about the optional parameters? - -We can add them below the email parameter and set `required: false`. However, if we had more than two optional parameters, and most APIs do, the UI would become overwhelming for the users. To avoid this, we use a UI element named **collection** (usually called 'Additional Fields') to group all the optional parameters together. - -1. Add the following below the `email` field in `packages/nodes-base/nodes/FriendGrid/FriendGrid.node.ts`. - - ```typescript - { - displayName: 'Additional Fields', - name: 'additionalFields', - type: 'collection', - placeholder: 'Add Field', - default: {}, - displayOptions: { - show: { - resource: [ - 'contact', - ], - operation: [ - 'create', - ], - }, - }, - options: [ - { - displayName: 'First Name', - name: 'firstName', - type: 'string', - default: '', - }, - { - displayName: 'Last Name', - name: 'lastName', - type: 'string', - default: '', - }, - ], - }, - ``` - -2. Stop the current n8n process by pressing ctrl + c in the terminal in which you are running n8n. -3. Run again, by entering the following in the terminal. - ```bash - npm run dev - ``` -4. Go to [localhost:8080](http://localhost:8080/), refresh the page, and open the node again. - -The node should now look like in the following image. - -![FriendGrid's all fields](/_images/integrations/creating-nodes/friendgrid-all-fields.png) - -Now all our optional fields are presented in the UI and can be set individually depending on the user’s use-case. - -## Creating the UI for credentials' - -Most REST APIs use some sort of authentication mechanism. FriendGrid's REST API uses API Keys. The API Key informs them about who is making the request to their system and gives you access to all the functionality that the API provides. Given all the things it can do, this has to be treated as a sensitive piece of information and should be kept private. - -n8n gives you the ability to ask for sensitive information using credentials. In the credentials, you can use all the generally available UI elements. Additionally, the data that is stored using the credentials would be encrypted before being saved to the database. In order to do that, n8n uses an encryption key. - -With that in mind, let’s create the UI to ask for the user’s FriendGrid API Key. The process of creating and registering credentials is similar to that of creating and registering the node: - -1. Go to `packages/nod's-base/credentials`.' -2. Within the credentials folder, create a file named `FriendGridApi.credentials.ts`. -3. Paste the following code. - -```typescript -import { - ICredentialType, - NodePropertyTypes, -} from 'n8n-workflow'; - -export class FriendGridApi implements ICredentialType { - name = 'friendGridApi'; - displayName = 'FriendGrid API'; - documentationUrl = 'friendGrid'; - properties = [ - { - displayName: 'API Key', - name: 'apiKey', - type: 'string' as NodePropertyTypes, - default: '', - }, - ]; -} -``` - -4. Go to `/packages/nodes-base/package.json`. -5. Paste `"dist/credentials/FriendGridApi.credentials.js",` in the credentials array to register the credentials (in an alphabetical order). -6. Got to `packages/nodes-base/nodes/FriendGrid/FriendGrid.node.ts`. -7. Associate the credentials with the node by adding the following to `description.credentials`. - - ```typescript - { - name: 'friendGridApi', - required: true, - }, - ``` - -8. Stop the current n8n process by pressing ctrl + c in the terminal in which you are running n8n. -9. Run again, by entering the following in the terminal. - ```bash - npm run dev - ``` - -When you go to the Node Editor view, you should see the following. - -![FriendGrid's create credentials](/_images/integrations/creating-nodes/friendgrid-create-credentials.png) - -![FriendGrid's credentials](/_images/integrations/creating-nodes/friendgrid-credentials.png) - - -## Mapping the UI fields to the API - -With the UI that we added, we now have all the data that we need to make a request to the FriendGrid API and create contacts. - -This is where the `execute` method comes into play. Every time the node is executed, this method will be run. Within this method, we can have access to the input items and to the parameters that the user set in the UI, including the credentials. -To map the fields to the API, perform the following steps: - -1. Go to `package/nodes-base/nodes/FriendGrid.node.ts`. -2. Replace the current `execute` method with the following code. - -```typescript -async execute(this: IExecuteFunctions): Promise { - let responseData; - const resource = this.getNodeParameter('resource', 0) as string; - const operation = this.getNodeParameter('operation', 0) as string; - //Get credentials the user provided for this node - const credentials = await this.getCredentials('friendGridApi') as IDataObject; - - if (resource === 'contact') { - if (operation === 'create') { - // get email input - const email = this.getNodeParameter('email', 0) as string; - // get additional fields input - const additionalFields = this.getNodeParameter('additionalFields', 0) as IDataObject; - const data: IDataObject = { - email, - }; - - Object.assign(data, additionalFields); - - //Make http request according to - const options: OptionsWithUri = { - headers: { - 'Accept': 'application/json', - 'Authorization': `Bearer ${credentials.apiKey}`, - }, - method: 'PUT', - body: { - contacts: [ - data, - ], - }, - uri: `https://api.sendgrid.com/v3/marketing/contacts`, - json: true, - }; - - responseData = await this.helpers.request(options); - } - } - - // Map data to n8n data - return [this.helpers.returnJsonArray(responseData)]; -} -``` - -3. Stop the current n8n process by pressing ctrl + c in the terminal in which you are running n8n. -4. Run again, by entering the following in the terminal. - ```bash - npm run dev - ``` -5. Enter the credentials (FriendGrid API Key), contact parameters, and execute the node. - - Instructions to find the FriendGrid API Key can be found [here](https://sendgrid.com/docs/ui/account-and-settings/api-keys/). - -If everything went well, you should see the following. - -![Creating a contact in FriendGrid with n8n](/_images/integrations/creating-nodes/create-contact-friendgrid.png) - -Now we can successfully create contacts in FriendGrid from n8n. - -## Processing multiples items - -In real life, you'll probably have a workflow with more than one node. Our current implementation does not play well with the other nodes. If the data is coming into our FriendGrid node from another node, and that outputs, for example, two contacts, our node will process just the first contact. We want our node to process as many items as it receives. - -This is when the `this.getInputData()` function comes into play. Let's update our node so that it can process multiple items. - -1. In the Editor UI, create a new workflow. Add a Function node and connect it to the Start node. -2. Open the function node and replace the existing code with the following. - -```javascript - return [ - { - json: { - name: 'ricardo@n8n.io' - } - }, - { - json: { - name: 'hello@n8n.io' - } - }, -] -``` - -3. Execute the Function node. We're using the function node for testing, but you can think of it as any node that is returning “two people” (or more). These two people need to be added to FriendGrid as contacts. - - ![Output of the Function node](/_images/integrations/creating-nodes/function-node-output.png) - -4. Add a FriendGrid node to the workflow and connect it to the Function node. Add an expression in the ***Email*** field of the FriendGrid node and reference the ***name*** property that the Function node outputs. - - ![Using expressions in the FriendGrid node](/_images/integrations/creating-nodes/expressions-friendgrid.png) - -5. Replace the existing `execute` method with the following: - - ```typescript - async execute(this: IExecuteFunctions): Promise { - const items = this.getInputData(); - let responseData; - const returnData = []; - const resource = this.getNodeParameter('resource', 0) as string; - const operation = this.getNodeParameter('operation', 0) as string; - //Get credentials the user provided for this node - const credentials = await this.getCredentials('friendGridApi') as IDataObject; - - for (let i = 0; i < items.length; i++) { - if (resource === 'contact') { - if (operation === 'create') { - // get email input - const email = this.getNodeParameter('email', i) as string; - - // i = 1 returns ricardo@n8n.io - // i = 2 returns hello@n8n.io - - // get additional fields input - const additionalFields = this.getNodeParameter('additionalFields', i) as IDataObject; - const data: IDataObject = { - email, - }; - - Object.assign(data, additionalFields); - - //Make http request according to - const options: OptionsWithUri = { - headers: { - 'Accept': 'application/json', - 'Authorization': `Bearer ${credentials.apiKey}`, - }, - method: 'PUT', - body: { - contacts: [ - data, - ], - }, - uri: `https://api.sendgrid.com/v3/marketing/contacts`, - json: true, - }; - - responseData = await this.helpers.request(options); - returnData.push(responseData); - } - } - } - // Map data to n8n data structure - return [this.helpers.returnJsonArray(returnData)]; - } - ``` - -6. Execute the workflow. - -If you open the FriendGrid node, you should see the following. - -![Output of the FriendGrid node](/_images/integrations/creating-nodes/final-friendgrid.png) - -As showcased above, both the items were processed. That’s how all nodes in n8n work (with a few exceptions). They will automatically iterate over all the items and process them. - -Let’s go over the final version of the `execute` method' We are getting the items returned by the `this.getInputData()` function and iterating over all of them. Additionally, while doing so, we use the item index to get the correct parameter value using the function `this.getNodeParameters()`. For example, with the following input: - -```javascript -[ - { - json: { - name: 'ricardo@n8n.io' - } - }, - { - json: { - name: 'hello@n8n.io' - } - }, -] -``` - -The `this.getNodeParameters(ParameterName, index)`function outputs the following: - -| Index | Parameter Name | Output | -|-------|----------------|-------------------| -| 0 | email | ricardo@n8n.io | -| 1 | email | hello@n8n.io | - -We used the `this.helpers.request(options)` method to make the HTTP Request that creates the contact in FriendGrid. The FriendGrid endpoint returns something like this: - -```javascript -{ - job_id: "b82aca74-3640-4097-85ec-7801d833c2cb" -} -``` - -We then used the `this.helpers.returnJsonArray()` method to map the API’s output data to n8n's data structure. The node then ends up returning the data like the following: - -```javascript -[ - { - json:{ - job_id: "b82aca74-3640-4097-85ec-7801d833c2cb" - } - } -] -``` - - -## Summary - -In this tutorial, we implemented the "Create a Contact" functionality of the FriendGrid API. First of all, we made the node show up in the Editor UI and in the Create Node menu with FriendGrid's branding. Then, we added the fields necessary to create a contact in FriendGrid. We also added the credentials so that the API Key could be stored safely. Finally, we mapped all the parameters to the FriendGrid API. - -This is just the tip of the iceberg. We built a regular node that consumes a REST API, but a regular node can do everything that can be done with Node.js. Aside from regular nodes you can also build Trigger nodes. - -## Next steps - -Once you have created the node and want to contribute to n8n, please check the [Node Review Checklist](/integrations/creating-nodes/code/review-checklist/). Make sure you complete the checklist before creating a pull request. - -## Next steps - -* [Deploy your node](/integrations/creating-nodes/deploy/). -* View an example of a programmatic node: n8n's [Mattermost node](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Mattermost){:target=_blank .external-link}. -* Learn about [node versioning](/integrations/creating-nodes/build/reference/node-versioning/). diff --git a/docs/integrations/creating-nodes/build/index.md b/docs/integrations/creating-nodes/build/index.md index 7ad500f95..ee1291216 100644 --- a/docs/integrations/creating-nodes/build/index.md +++ b/docs/integrations/creating-nodes/build/index.md @@ -1,4 +1,4 @@ -# Overview +# Build a node This section provides tutorials on building nodes. It covers: diff --git a/docs/integrations/creating-nodes/build/programmatic-style-node.md b/docs/integrations/creating-nodes/build/programmatic-style-node.md index 45daac3b3..0e642f9be 100644 --- a/docs/integrations/creating-nodes/build/programmatic-style-node.md +++ b/docs/integrations/creating-nodes/build/programmatic-style-node.md @@ -473,3 +473,4 @@ You need to update the `package.json` to include your own information, such as y * [Deploy your node](/integrations/creating-nodes/deploy/). * View an example of a programmatic node: n8n's [Mattermost node](https://github.com/n8n-io/n8n/tree/master/packages/nodes-base/nodes/Mattermost){:target=_blank .external-link}. This is an example of a more complex programmatic node structure. * Learn about [node versioning](/integrations/creating-nodes/build/reference/node-versioning/). +* Make sure you understand key concepts: [item linking](/data/data-mapping/data-item-linking/item-linking-concepts/) and [data structures](/data/data-structure/). diff --git a/docs/integrations/creating-nodes/build/reference/code-standards.md b/docs/integrations/creating-nodes/build/reference/code-standards.md index ae29bcdd0..c7f6d0151 100644 --- a/docs/integrations/creating-nodes/build/reference/code-standards.md +++ b/docs/integrations/creating-nodes/build/reference/code-standards.md @@ -79,7 +79,7 @@ When reusing the internal name, you must ensure that only one field is visible t ## Detailed guidelines for writing a programmatic-style node -These guidelines apply when building nodes using the programmatic node-building style. They aren't relevant when using the declarative style. For more information on different node-building styles, refer to [Choose your node building approach](/integrations/creating-nodes/choose-node-method/). +These guidelines apply when building nodes using the programmatic node-building style. They aren't relevant when using the declarative style. For more information on different node-building styles, refer to [Choose your node building approach](/integrations/creating-nodes/plan/choose-node-method/). ### Don't change incoming data @@ -100,4 +100,4 @@ const response = await this.helpers.httpRequest(options); This uses the npm package [`request-promise-native`](https://github.com/request/request-promise-native){:target=_blank .external-link}, which is the basic npm `request` module but with promises. For a full set of options refer to [the underlying `request` options documentation](https://github.com/request/request#requestoptions-callback){:target=_blank .external-link}. -Refer to [HTTP helpers](/integrations/creating-nodes/code/http-helpers/) for documentation and migration instructions for the deprecated `this.helpers.request`. +Refer to [HTTP helpers](/integrations/creating-nodes/build/reference/http-helpers/) for documentation and migration instructions for the deprecated `this.helpers.request`. diff --git a/docs/integrations/creating-nodes/build/reference/index.md b/docs/integrations/creating-nodes/build/reference/index.md index 6f61cc3e3..98d2b8323 100644 --- a/docs/integrations/creating-nodes/build/reference/index.md +++ b/docs/integrations/creating-nodes/build/reference/index.md @@ -1,7 +1,7 @@ -# Overview +# Node building reference This section contains reference information, including details about: * [Node UI elements](/integrations/creating-nodes/build/reference/ui-elements/) * [Organizing your node files](/integrations/creating-nodes/build/reference/node-file-structure/) -* Key parameters in your node's [base file](/integrations/creating-nodes/build/reference/node-base-files/) and [credentials file](/integrations/creating-nodes/build/reference/credentials-files/). \ No newline at end of file +* Key parameters in your node's [base file](/integrations/creating-nodes/build/reference/node-base-files/) and [credentials file](/integrations/creating-nodes/build/reference/credentials-files/). diff --git a/docs/integrations/creating-nodes/build/reference/node-base-files.md b/docs/integrations/creating-nodes/build/reference/node-base-files.md index 4dc8cce50..4f15e9cb9 100644 --- a/docs/integrations/creating-nodes/build/reference/node-base-files.md +++ b/docs/integrations/creating-nodes/build/reference/node-base-files.md @@ -4,7 +4,7 @@ The node base file contains the core code of your node. All nodes must have a ba 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](){: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. +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 @@ -300,6 +300,8 @@ description: INodeTypeDescription = { TODO: more info on the routing object ### routing.output +include postReceive actions, including ability to dynamically disable - see DOC-400 + ### routing.request ### routing.send diff --git a/docs/integrations/creating-nodes/build/reference/paired-items.md b/docs/integrations/creating-nodes/build/reference/paired-items.md index a08f7663e..ed1808104 100644 --- a/docs/integrations/creating-nodes/build/reference/paired-items.md +++ b/docs/integrations/creating-nodes/build/reference/paired-items.md @@ -1,33 +1,3 @@ -# Paired items +# Item linking -!!! note "Programmatic-style nodes only" - This guidance applies to programmatic-style nodes. If you're using declarative style, n8n handles paired items for you automatically. - -An n8n node operation consumes input items and produces output items. n8n generates an output item from a single input item, except in the Merge node, or any other node that combines or sums items. - -n8n needs to know which input item a given output item comes from. If this information is missing, expressions in other nodes may break. - -You must provide item pairing information when returning the output of your operations. You can do this using the `pairedItem` key. - -For example, assume there's a node that integrates with a ticket system such as JIRA or Trello, and you want to get a list of tickets by ID. Here is a simplified `execute()` function returning some output data and its paired input item key: - -```js -async execute(this: IExecuteFunctions): Promise { - - const items = this.getInputData(); - const returnData: INodeExecutionData[] = []; - let responseData; - - for (let i = 0; i < items.length; i++) { - const ticketId = this.getNodeParameter('ticketId', i); - responseData = await someApiRequest.call(this, 'GET', `/tickets/${ticketId}`); - returnData.push({ - json: responseData, - pairedItem: { - item: i, - }, - }); - } - return returnData; -} -``` +--8<-- "_snippets/data/data-mapping/item-linking-node-creators.md" diff --git a/docs/integrations/creating-nodes/build/reference/ui-elements.md b/docs/integrations/creating-nodes/build/reference/ui-elements.md index 0b4950c39..4b2e24b4a 100644 --- a/docs/integrations/creating-nodes/build/reference/ui-elements.md +++ b/docs/integrations/creating-nodes/build/reference/ui-elements.md @@ -424,3 +424,102 @@ Use the `fixedCollection` type to group fields that are semantically related. ![JSON](/_images/integrations/creating-nodes/json.png) +## Resource locator + +![Resource locator](/_images/integrations/creating-nodes/resource-locator.png) + +The resource locator element helps users find a specific resource in an external service, such as a card or label in Trello. + +The following options are available: + +* ID +* URL +* List: allows users to select or search from a prepopulated list. This option requires more coding, as you must populate the list, and handle searching if you choose to support it. + +You can choose which types to include. + +Example: + +```typescript +{ + displayName: 'Card', + name: 'cardID', + type: 'resourceLocator', + default: '', + description: 'Get a card' + modes: [ + { + displayName: 'ID', + name: 'id', + type: 'string', + hint: 'Enter an ID', + validation: [ + { + type: 'regex', + properties: { + regex: '^[0-9]' + errorMessage: 'The ID must start with a number' + }, + }, + ], + placeholder: '12example', + // How to use the ID in API call + url: '=http://api-base-url.com/?id={{$value}}' + }, + displayName: 'URL', + name: 'url', + type: 'string', + hint: 'Enter a URL', + validation: [ + { + type: 'regex', + properties: { + regex: '^http' + errorMessage: 'Invalid URL' + }, + }, + ], + placeholder: 'https://example.com/card/12example/', + // How to get the ID from the URL + extractValue: { + type: 'regex', + regex: 'example\.com\/card\/([0-9]*.*)\/' + }, + displayName: 'List', + name: 'list', + type: 'list', + typeOptions: { + // You must always provide a search method + // Write this method within the methods object in your base file + // The method must populate the list, and handle searching if searchable: true + searchListMethod: 'searchMethod' + // If you want users to be able to search the list + searchable: true, + // Set to true if you want to force users to search + // When true, users can't browse the list + // Or false if users can browse a list + searchFilterRequired: true + } + ], + displayOptions: { // the resources and operations to display this element with + show: { + resource: [ + // comma-separated list of resource names + ], + operation: [ + // comma-separated list of operation names + ] + } + }, +} +``` + +Refer to the following for live examples: + +* Refer to [`CardDescription.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Trello/CardDescription.ts){:target=_blank .external-link} and [`Trello.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Trello/Trello.node.ts){:target=_blank .external-link} in n8n's Trello node for an example of a list with search that includes `searchFilterRequired: true`. +* Refer to [`GoogleDrive.node.ts`](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/nodes/Google/Drive/GoogleDrive.node.ts){:target=_blank .external-link} for an example where users can browse the list or search. + + + + + diff --git a/docs/integrations/creating-nodes/deploy/index.md b/docs/integrations/creating-nodes/deploy/index.md index 171c621e2..5079c6304 100644 --- a/docs/integrations/creating-nodes/deploy/index.md +++ b/docs/integrations/creating-nodes/deploy/index.md @@ -1,4 +1,4 @@ -# Overview +# Deploy a node This section contains details on how to deploy and share your node. diff --git a/docs/integrations/creating-nodes/index.md b/docs/integrations/creating-nodes/index.md index 162e386c9..bedb1b38f 100644 --- a/docs/integrations/creating-nodes/index.md +++ b/docs/integrations/creating-nodes/index.md @@ -1,4 +1,4 @@ -# Overview +# Creating nodes Learn how to build your own custom nodes. @@ -10,10 +10,11 @@ This section includes: * How to [share your node](/integrations/creating-nodes/deploy/submit-community-nodes/) with the community, or use it as a [private node](/integrations/creating-nodes/deploy/install-private-nodes/). * [Reference material](/integrations/creating-nodes/build/reference/), including UI elements and information on the individual files that make up a node. -## Technical difficulty +## Prerequisites This section assumes the following: * Some familiarity with JavaScript and TypeScript. * Ability to manage your own development environment, including git. -* Knowledge of npm, including creating and submitting packages. \ No newline at end of file +* Knowledge of npm, including creating and submitting packages. +* Familiarity with n8n, including a good understanding of [data structures](/data/data-structure/) and [item linking](/data/data-mapping/data-item-linking/). diff --git a/docs/integrations/creating-nodes/plan/index.md b/docs/integrations/creating-nodes/plan/index.md index b9a3cc1ea..4f985f7a3 100644 --- a/docs/integrations/creating-nodes/plan/index.md +++ b/docs/integrations/creating-nodes/plan/index.md @@ -1,4 +1,4 @@ -# Overview +# Plan a node This section provides guidance on designing your node, including key technical decisions such as choosing your node building style. diff --git a/docs/integrations/creating-nodes/test/index.md b/docs/integrations/creating-nodes/test/index.md index bc3a9d787..6752526bd 100644 --- a/docs/integrations/creating-nodes/test/index.md +++ b/docs/integrations/creating-nodes/test/index.md @@ -1,4 +1,4 @@ -# Overview +# Test a node This section contains information about testing your node. diff --git a/docs/reference/index.md b/docs/reference/index.md index d9aac0a43..0587498c9 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,4 +1,4 @@ -# Overview +# Reference This section provides reference information about n8n, including: @@ -7,4 +7,4 @@ This section provides reference information about n8n, including: * [Keyboard shortcuts](/reference/keyboard-shortcuts/) * [Glossary](/reference/glossary/) * [License](/reference/license/) -* [Data collection](/reference/data-collection/) \ No newline at end of file +* [Data collection](/reference/data-collection/) diff --git a/docs/reference/license.md b/docs/reference/license.md index a5f0f409f..3f8109dec 100644 --- a/docs/reference/license.md +++ b/docs/reference/license.md @@ -1,6 +1,6 @@ # License -n8n is [fair-code](http://faircode.io) licensed under the [Sustainable Use License](https://github.com/n8n-io/n8n/blob/master/LICENSE.md) +n8n is [fair-code](http://faircode.io) licensed under the [Sustainable Use License](https://github.com/n8n-io/n8n/blob/master/LICENSE.md){:target=_blank .external-link} and [n8n Enterprise License](https://github.com/n8n-io/n8n/blob/master/LICENSE_EE.md){:target=_blank .external-link}. ## License FAQs diff --git a/docs/reference/release-notes.md b/docs/reference/release-notes.md index d4b6053ac..04060f43c 100644 --- a/docs/reference/release-notes.md +++ b/docs/reference/release-notes.md @@ -1,5 +1,499 @@ # Release notes +## n8n@0.199.0 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.198.2...n8n@0.199.0){:target=_blank .external-link} for this version.
+**Release date:** 2022-10-21 + +This release includes new nodes, an improved workflow UI, performance improvements, and bug fixes. + +### New features + +
+ +#### New workflow experience + +This release brings a collection of UI changes, aimed at improving the workflow experience for users. This includes: + +* Removing the Start node, and adding help to guide users to find a trigger node. +* Improved node search. +* New nodes: Manual Trigger and Execute Workflow Trigger. + +
+ +* Core: block workflow updates on interim changes. +* Core: enable sending client credentials in the body of API calls. +* Editor: add automatic credential selection for new nodes. + +### New nodes + +
+ +#### Compare node + +The Compare Datasets node helps you compare data from two input streams. You can find documentation for the new node [here](/integrations/builtin/core-nodes/n8n-nodes-base.comparedatasets/). + +
+ +
+ +#### Execute Workflow Trigger node + +The Execute Workflow Trigger starts a workflow in response to another workflow. You can find documentation for the new node [here](/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflowtrigger/). + +
+ +
+ +#### Manual Trigger node + +The Manual Trigger allows you to start a workflow by clicking **Execute Workflow**, without any option to run it automatically. You can find documentation for the new node [here](/integrations/builtin/core-nodes/n8n-nodes-base.manualworkflowtrigger/). + +
+ +
+ +#### Schedule Trigger node + +This release introduces the Schedule Trigger node, replacing the Cron node. You can find documentation for the new node [here](/integrations/builtin/core-nodes/n8n-nodes-base.scheduletrigger/). + +
+ +### Node enhancements + +* Hubspot node: you can now use your Hubspot credentials in the HTTP Request node to make a [custom API call](/integrations/custom-operations/). +* Rundeck node: you can now use your Rundeck credentials in the HTTP Request node to make a [custom API call](/integrations/custom-operations/). + +### Bug fixes + +* Editor: fix a hover bug in the bottom menu. +* Editor: resolve performance issues when opening a node, or editing a code node, with a large amount of data. +* Editor: ensure workflows always stop when clicking the stop button. +* Editor: fix a bug that was causing text highlighting when mapping data in Firefox. +* Editor: ensure correct linting in the Code node editor. +* Editor: handle null values in table view. +* Elasticsearch node: fix a pagination issue. +* Google Drive node: fix typo. +* HTTP Request node: avoid errors when a response doesn't provide a content type. +* n8n node: fix a bug that was preventing the resource locator component from returning all items. + +### Contributors + +[AndLLA](https://github.com/AndLLA){:target=_blank .external-link} +[Nicholas Penree](https://github.com/drudge){:target=_blank .external-link} +[vcrwr](https://github.com/vcrwr){:target=_blank .external-link} + +## n8n@0.198.2 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.198.1...n8n@0.198.2){:target=_blank .external-link} for this version.
+**Release date:** 2022-10-14 + +This release fixes a bug affecting scrolling through parameter lists. + +## n8n@0.198.1 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.198.0...n8n@0.198.1){:target=_blank .external-link} for this version.
+**Release date:** 2022-10-14 + +This is a bug fix release. + +### Bug fixes + +* Editor: change the initial position of the Start node. +* Editor: align JSON view properties with their values. +* Editor: fix `BASE_PATH` for Vite dev mode. +* Editor: fix data pinning success source. + +### Contributor + +[Bram Kn](https://github.com/bramkn){:target=_blank .external-link} + + +## n8n@0.198.0 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.197.1...n8n@0.198.0){:target=_blank .external-link} for this version.
+**Release date:** 2022-10-14 + +!!! warning "Breaking changes" + Please note that this version contains breaking changes to the Merge node. You can read more about them [here](https://github.com/n8n-io/n8n/blob/master/packages/cli/BREAKING-CHANGES.md#01980){:target=_blank .external-link}. + +### New features + +* Editor: update the expressions display. +* Editor: update the n8n-menu component. + +### New nodes + +
+ +#### Code node + +This release introduces the Code node. This node replaces both the Function and Function Item nodes. Refer to the [Code node](/integrations/builtin/core-nodes/n8n-nodes-base.code/) documentation for more information. + +
+ +
+ +#### Venafi TLS Protect Cloud trigger node + +Start a workflow in response to events in your Venafi Cloud service. + +
+ +### Node enhancements + +* Citrix ADC node: add Certificate Install operation. +* Kafka node: add a **Use key** option for messages. +* MySQL node: use the resource locator component for table parameters, making it easier for users to browse and select their database fields from within n8n. + +### Bug fixes + +* Core, Editor: prevent overlap between running and pinning data. +* Core: expression evaluation of processes now respects `N8N_BLOCK_ENV_ACCESS_IN_NODE`. +* Editor: ensure the Axios base URL still works when hosted in a subfolder. +* Editor: fixes for horizontal scrollbar rendering. +* Editor: ensure the menu closes promptly when loading a credentials page. +* Editor: menu UI fixes. +* Box node: fix an issue that was causing the Create Folder operation to show extra items. +* GSuite Admin node: resolve issue that was causing the User Update operation to fail. +* GitLab trigger node: ensure this node activates reliably. +* HTTP Request node: ensure OAuth credentials work properly with predefined credentials. +* KoboToolbox node: fix the hook logs. +* SeaTable node: ensure link items show in response. +* Zoom node: resolve an issue that was causing missing output items. + +### Contributors + +[Jakob Backlund](https://github.com/jbacklund){:target=_blank .external-link} +[Yan Jouanique](https://github.com/Yann-J){:target=_blank .external-link} + +## n8n@0.197.1 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.197.0...n8n@0.197.1){:target=_blank .external-link} for this version.
+**Release date:** 2022-10-10 + +This is a bug fix release. It resolves an issue with display width on the resource locator UI component. + +## n8n@0.197.0 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.196.0...n8n@0.197.0){:target=_blank .external-link} for this version.
+**Release date:** 2022-10-10 + +This release includes six new nodes, focused around infrastructure management. It also adds support for drag and drop data mapping in the JSON input view, and includes bug fixes. + +### New features + +* Core: improve light versioning support in declarative node design. +* Editor UI: data mapping for JSON view. You can now map data using drag and drop from JSON view, as well as table view. + +### New nodes + +
+ +#### AWS Certificate Manager + +A new integration with AWS Certificate Manager. You can find the documentation [here](/integrations/builtin/app-nodes/n8n-nodes-base.awsCertificateManager/). + +
+ +
+ +#### AWS Elastic Load Balancing + +Manage your AWS load balancers from your workflow using the new AWS Elastic Load Balancing node. You can find the documentation [here](/integrations/builtin/app-nodes/n8n-nodes-base.awsElb/). + +
+ +
+ +#### Citrix ADC + +Citrix ADC is an application delivery and load balancing solution for monolithic and microservices-based applications. You can find the documentation [here](/integrations/builtin/app-nodes/n8n-nodes-base.citrixAdc/). + +
+ +
+ +#### Cloudflare + +Cloudflare provides a range of services to manage and protect your websites. This new node allows you to manage zone certificates in Cloudflare from your workflows. You can find the documentation [here](/integrations/builtin/app-nodes/n8n-nodes-base.cloudflare/). + +
+ +
+ +#### Venafi nodes + +This release includes two new Venafi nodes, to integrate with their Protect TLS service. + +
+ +### Node enhancements + +Crypto node: add SHA3 support. + +### Bug fixes + +* CLI: cache generated assets in a user-writeable directory. +* Core: prevent excess runs when data is pinned in a trigger node. +* Core: ensure hook URLs always added correctly. +* Editor: a fix for an issue affecting linked items in combination with data pinning. +* Editor: resolve a bug with the binary data view. +* GitHub trigger node: ensure trigger executes reliably. +* Microsoft Excel node: fix pagination issue. +* Microsoft ToDo node: fix pagination issue. + +### Contributors + +[Stratos Theodorou](https://github.com/eeVoskos){:target=_blank .external-link} + +## n8n@0.196.0 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.195.5...n8n@0.196.0){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-30 + +This release includes major new features: + +* Better item linking +* New built-in variables and methods +* A redesigned main navigation +* New nodes, as well as an overhaul of the HTTP Request node + +It also contains bug fixes and node enhancements. + +### New features + +
+ +#### Improved item linking + +Introducing improved support for item linking (paired items). Item linking is a key concept in the n8n data flow. Learn more in [Data item linking](/data/data-mapping/data-item-linking/). + +
+ +
+ +#### Overhauled built-in variables + +n8n's [built-in methods and variables](/code-examples/methods-variables-reference/) have been overhauled, introducing new variables, and providing greater consistency in behavior and naming. + +
+ +
+ +#### Redesigned main navigation + +We've redesigned the main navigation (the left hand menu) to create a simpler user experience. + +
+ +#### Other new features + +* Improved error text when loading options in a node. +* On reset, share unshared credentials with the instance owner. + +### New nodes + +
+ +#### n8n node + +The [n8n node](/integrations/builtin/core-nodes/n8n-nodes-base.n8n/) allows you to consume the n8n API in your workflows. + +
+ +
+ +#### WhatsApp Business Platform node + +The [WhatsApp Business Platform](/integrations/builtin/app-nodes/n8n-nodes-base.whatsapp/) node allows you to use the WhatsApp Business Platform Cloud API in your workflows. + +
+ +### Node enhancements + +* HTTP Request node: a major overhaul. It's now much simpler to build a custom API request. Refer to the [HTTP Request node documentation](/integrations/builtin/core-nodes/n8n-nodes-base.httpRequest/) for more information. +* RabbitMQ trigger node: now automatically reconnects on disconnect. +* Slack node: add the 'get many' operation for users. + +### Bug fixes + +* Build: add typing for SSE channel. +* Build: fix lint issue. +* CLI: add git to all Docker images +* CLI: disable X-Powered-By: Express header. +* CLI: disable CORS on SSE connections in production. +* Core: remove commented out lines. +* Core: delete unused dependencies. +* Core: fix and harmonize documentation links for nodes. +* Core: remove the --forceExit flag from CLI tests. +* Editor: add missing event handler to accordion component. +* Editor: fix Storybook setup. +* Editor: ensure BASE_URL replacement works correctly on Windows. +* Editor: fix parameter input field focus. +* Editor: make lodash aliases work on case-sensitive file systems. +* Editor: fix an issue affecting copy-pasting workflows into pinned data in the code editor. +* Editor: ensure the run data pagination selector displays when appropriate. +* Editor: ensure the run selector can open. +* Editor: tidy up leftover i18n references in the node view. +* Editor: correct an i18n string. +* Editor: resolve slow loading times for node types, node creators, and push connections in the settings view. +* Nodes: update descriptions in the Merge node +* Nodes: ensure the card ID property displays for completed checklists in the Trello node. +* Nodes: fix authentication for the new verions of Wekan. +* Nodes: ensure form names list correctly in the Wufoo trigger node. + +### Contributors + +[Cristobal Schlaubitz Garcia](https://github.com/CxGarcia){:target=_blank .external-link} + +## n8n@0.195.5 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.195.4...n8n@0.195.5){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-23 + +This is a bug fix release. It fixes an issue with extracting values in expressions. + +## n8n@0.195.4 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.195.3...n8n@0.195.4){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-22 + +This release: + +* Adds the ability to resize the main node panel. +* Resolves an issue with resource locator in expressions. + +## n8n@0.195.3 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.195.2...n8n@0.195.3){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-22 + +This is a bug fix release. + +* Editor: fix an expressions bug affecting numbers and booleans. +* Added support for setting the TDS version in Microsoft SQL credentials. + +## n8n@0.195.2 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.195.1...n8n@0.195.2){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-22 + +This is a bug fix release. It resolves an issue with MySQL migrations. + + +## n8n@0.195.1 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.195.0...n8n@0.195.1){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-21 + +This is a bug fix release. It resolves an issue with Postgres migrations. + +## n8n@0.195.0 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.194.0...n8n@0.195.0){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-21 + +This release introduces user management and credential sharing for our Cloud platform. It also contains other enhancements and bug fixes. + +### New features + +
+ +#### User management and credential sharing for Cloud + +This release adds support for our existing [user management](/hosting/user-management/) functionality to Cloud, and introduces a new feature: [credential sharing](/credentials/credential-sharing/). Credential sharing is currently only available on Cloud. + +
+ +Also in this release: + +* Added a `resourceLocator` parameter type for nodes, and started upgrading our built-in nodes to use it. This new option helps users who need to specify the ID of a record or item in an external service. For example, when using the Trello node, you can now search for a specific card by ID, URL, or do a free text search for card titles. Node builders can learn more about working with this new UI element in our [UI elements](/integrations/creating-nodes/build/reference/ui-elements/) documentation. +* Cache npm dependencies to improve performance on self-hosted n8n + +### Bug fixes + +* Box node: fix an issue that sometimes prevented response data from being returned. +* CLI: prevent n8n from crashing when it encounters an error in poll method. +* Core: prevent calls to constructor, to forbid arbitrary code execution. +* Editor: fix the output panel for Wait node executions. +* HTTP node: ensure instance doesn't crash when batching enabled. +* Public API: corrections to the OAuth schema. +* Xero node: fix an issue that was causing line amount types to be ignored when creating new invoices. + +### Contributors + +[Ikko Ashimine](https://github.com/eltociear){:target=_blank .external-link} + + +## n8n@0.194.0 + +View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.193.5...n8n@0.194.0){:target=_blank .external-link} for this version.
+**Release date:** 2022-09-15 + +This release includes new nodes: a Gmail trigger, Google Cloud Storage, and Adalo. It also contains major overhauls of the Gmail and Merge nodes. + +### New features + +* CLI: load all nodes and credentials code in isolation. +* Core, Editor UI: introduce support for node deprecation. +* Editor: implement HTML sanitization for Notification and Message components. +* Editor: display the input number on multi-input nodes. + +### New nodes + +
+ +#### Adalo + +Adalo is a low code app builder. Refer to our [Adalo node documentation](/integrations/builtin/app-nodes/n8n-nodes-base.adalo/) for more information. + +
+ +
+ +#### Google Cloud Storage + +n8n now has a [Google Cloud Storage node](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudStorage/). + +
+ +
+ +#### Gmail Trigger + +n8n now has a [Gmail trigger node](/integrations/builtin/trigger-nodes/n8n-nodes-base.gmailTrigger/). This allows you to trigger workflows in response to a Gmail account receiving an email. + +
+ + +### Node enhancements + +* Gmail node: this release includes an overhaul of the [Gmail node](/integrations/builtin/app-nodes/n8n-nodes-base.gmail/), with updated resources and operations. +* Merge node: a major overhaul. Merge mode's have new names, and have been simplified. Refer to the [Merge node documentation](/integrations/builtin/core-nodes/n8n-nodes-base.merge/) to learn more. +* MongoDB node: updated the Mongo driver to 4.9.1. + + +### Bug fixes + +* CLI: core: address Dependabot warnings. +* CLI: avoid scanning unnecessary directories on Windows. +* CLI: load nodes and directories on Windows using the correct file path. +* CLI: ensure password reset triggers internal and external hooks. +* CLI: use absolute paths for loading custom nodes and credentials. +* Core: returnJsonArray helper no longer breaks nodes that return no data. +* Core: fix an issue with node renaming and expressions. +* Core: update OAuth endpoints to use the instance base URL. +* Nodes: resolved an issue that was preventing versioned nodes from loading. +* Public API: better error handling for bad requests. +* AWS nodes: fixed an issue with credentials testing. +* GoogleBigQuery node: fix for empty responses when creating records. +* Hubspot node: correct the node name on the canvas. + +### Contributors + +[Rhys Williams](https://github.com/rhyswilliamsza){:target=_blank .external-link} + ## n8n@0.193.5 View the [commits](https://github.com/n8n-io/n8n/compare/n8n@0.193.4...n8n@0.193.5){:target=_blank .external-link} for this version.
@@ -459,7 +953,7 @@ This release contains bug fixes and node enhancements. ### Bug fixes * Editor: Fix an error that occured after repeated executions. -* [EmailReadImap node](/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/): improve handling of network problems. +* [EmailReadImap node](/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/): improve handling of network problems. * [Google Drive node](/integrations/builtin/app-nodes/n8n-nodes-base.googleDrive/): process input items using the list operation. * [Telegram node](/integrations/builtin/app-nodes/n8n-nodes-base.telegram/): fix for a bug affecting sending binary data (images, documents and so on). @@ -706,7 +1200,7 @@ This release adds a new trigger node for Cal.com. Refer to the [Cal trigger docu * Resolve crashes in queue mode. * Correct delete button hover spacing. * Resolve a bug causing stuck loading states. -* [EmailReadImap node](/integrations/core-nodes/n8n-nodes-base.imapEmail){:target=_blank}: improve error handling. +* [EmailReadImap node](/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/){:target=_blank}: improve error handling. * [Hubspot node](/integrations/builtin/app-nodes/n8n-nodes-base.hubspot/){:target=_blank}: fix contact loading. ### Contributors @@ -1089,7 +1583,7 @@ You can now download binary data from individual nodes in your workflow. ### Bug fixes * **core:** Fix crash on webhook when last node did not return data -* [EmailReadImap Node:](/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/) Fix issue that crashed process if node was configured wrong. +* [EmailReadImap Node:](/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/) Fix issue that crashed process if node was configured wrong. * [Google Tasks Node:](/integrations/builtin/app-nodes/n8n-nodes-base.googleTasks/) Fix 'Show Completed' option and hide title field where not needed. * [NocoDB Node:](/integrations/builtin/app-nodes/n8n-nodes-base.nocoDb/) Fix pagination. * [Salesforce Node:](/integrations/builtin/app-nodes/n8n-nodes-base.salesforce/) Fix issue that 'status' did not get used for Case => Create & Update @@ -2807,7 +3301,7 @@ For a comprehensive list of changes, check out the [commits](https://github.com/ ### Enhanced nodes * [Google Cloud Firestore:](/integrations/builtin/app-nodes/n8n-nodes-base.googleCloudFirestore/) Added the functionality for GeoPoint parsing and added ISO-8601 format for date validation -* [IMAP Email:](/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/) Added the Force reconnect option +* [IMAP Email:](/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/) Added the Force reconnect option * [Paddle:](/integrations/builtin/app-nodes/n8n-nodes-base.paddle/) Added the Use Sandbox environment API parameter * [Spotify:](/integrations/builtin/app-nodes/n8n-nodes-base.spotify/) Added the Position parameter to the Add operation of the Playlist resource * [WooCommerce:](/integrations/builtin/app-nodes/n8n-nodes-base.wooCommerce/) Added the Include Credentials in Query parameter @@ -2990,7 +3484,7 @@ For a comprehensive list of changes, check out the [commits](https://github.com/ ### Bug fixes * [AWS SQS:](/integrations/builtin/app-nodes/n8n-nodes-base.awsSqs/) Fixed an issue with API version and casing -* [IMAP:](/integrations/builtin/core-nodes/n8n-nodes-base.imapEmail/) Fixed re-connection issue +* [IMAP:](/integrations/builtin/core-nodes/n8n-nodes-base.emailimap/) Fixed re-connection issue * [Keap:](/integrations/builtin/app-nodes/n8n-nodes-base.keap/) Fixed an issue with the Opt In Reason parameter * [Salesforce:](/integrations/builtin/app-nodes/n8n-nodes-base.salesforce/) Fixed an issue with loading custom fields diff --git a/docs/try-it-out/index.md b/docs/try-it-out/index.md index 10591826a..79ce81f81 100644 --- a/docs/try-it-out/index.md +++ b/docs/try-it-out/index.md @@ -1,4 +1,4 @@ -# Overview +# Try it out This section gets you up and running with building workflows in n8n. diff --git a/docs/try-it-out/longer-introduction.md b/docs/try-it-out/longer-introduction.md index 72101f1b7..55b7357b1 100644 --- a/docs/try-it-out/longer-introduction.md +++ b/docs/try-it-out/longer-introduction.md @@ -13,6 +13,8 @@ This guide shows you how to automate a task using a workflow in n8n, explaining ## Step one: Install and run n8n +!!! note "Skip this section if you've already installed n8n or signed up for a Cloud account" + --8<-- "_snippets/try-it-out/install-run-n8n.md" ## Step two: Create a new workflow @@ -58,7 +60,7 @@ The [NASA node](/integrations/builtin/app-nodes/n8n-nodes-base.nasa/) allows you 6. By default, DONKI Solar Flare provides data for the past 30 days. To limit it to just the last week, use **Additional Fields**: 1. Select **Add field**. 2. Select **Start date**. - 3. To get a report starting from a week ago, you can use an expression: next to **Start date**, select **Parameter options** ![Parameter options icon](/_images/try-it-out/parameter-options.png) > **Add Expression**. n8n opens the **Edit Expression** modal. + 3. To get a report starting from a week ago, you can use an expression: next to **Start date**, select the **Expression** tab. n8n opens the **Edit Expression** modal. 4. In the **Expression** field, enter the following expression: ```js {{$today.minus({days: 7}).toFormat('yyyy-MM-dd')}} @@ -83,7 +85,7 @@ Add the If node: 3. Select **If** to add the node to the canvas. n8n opens the node. 4. Select **Add condition** > **String**. 5. You need to check the value of the `classType` property in the NASA data. To do this: - 1. Next to **Value 1**, select **Parameter options** ![Parameter options icon](/_images/try-it-out/parameter-options.png) > **Add Expression**. n8n opens the expressions editor for this field. + 1. Next to **Value 1**, select the **Expression** tab. n8n opens the expressions editor for this field. 2. Select **Current Node** > **Input Data** > **JSON** > **classType**. n8n adds the expression to the **Expression** editor, and displays a sample output. !!! note "Make sure you ran the NASA node in the previous section" @@ -109,7 +111,7 @@ The last step of the workflow is to send the two reports about solar flares. For 6. Go to [Postbin](https://www.toptal.com/developers/postbin/) and select **Create Bin**. 7. Copy the bin ID. It looks similar to `1651063625300-2016451240051`. 8. In n8n, paste your Postbin ID into **Bin ID**. -9. Now, configure the data to send to Postbin. Next to **Bin Content**, select **Parameter options** ![Parameter options icon](/_images/try-it-out/parameter-options.png) > **Add Expression**. +9. Now, configure the data to send to Postbin. Next to **Bin Content**, select the **Expression** tab. n8n opens the expressions editor for this field. 10. Select **Current Node** > **Input Data** > **JSON** > **classType**. n8n adds the expression to the **Expression** editor, and displays a sample output. 11. The expression is: `{{$json["classType"]}}`. Add a message to it, so that the full expression is: ```js diff --git a/docs/try-it-out/quickstart.md b/docs/try-it-out/quickstart.md index 492b7d1d5..b0372bff8 100644 --- a/docs/try-it-out/quickstart.md +++ b/docs/try-it-out/quickstart.md @@ -4,13 +4,14 @@ This quickstart gives you a very quick taste of n8n. Its aim is to allow you to You will: -* Install the desktop app * Load a workflow from the workflow templates library * Add a node and configure it using expressions. * Run your first workflow ## Step one: Install and run n8n +!!! note "Skip this section if you've already installed n8n or signed up for a Cloud account" + --8<-- "_snippets/try-it-out/install-run-n8n.md" ## Step two: Open a workflow template @@ -40,10 +41,10 @@ Add a third node to message each customer and tell them their description. The C 2. Search for **Customer Messenger**. n8n shows a list of nodes that match the search. 3. Select **Customer Messenger (n8n training)** to add the node to the canvas. n8n opens the node automatically. 4. You're going to use [expressions](/code-examples/expressions/) to map in the **Customer ID** and create the **Message**: - 1. Next to **Customer ID**, select **Parameter options** ![Parameter options icon](/_images/try-it-out/parameter-options.png) > **Add Expression**. n8n opens the expressions editor for this field. + 1. Next to **Customer ID**, select the **Expression** tab. n8n opens the expressions editor for this field. 2. Select **Current Node** > **Input Data** > **JSON** > **customer_ID**. n8n adds the expression to the **Expression** editor, and displays a sample output. 3. Close the expressions editor. - 4. Next to **Message**, select **Parameter options** ![Parameter options icon](/_images/try-it-out/parameter-options.png) > **Add Expression**. n8n opens the expressions editor for this field. + 4. Next to **Message**, select the **Expression** tab. n8n opens the expressions editor for this field. 5. Copy this expression into the editor: ``` Hi {{$json.customer_name}}, Your description is {{$json.customer_description}} diff --git a/docs/workflows/executions.md b/docs/workflows/executions.md new file mode 100644 index 000000000..ddc6ba05d --- /dev/null +++ b/docs/workflows/executions.md @@ -0,0 +1,5 @@ +# Overview + +An execution is a single run of a worklow. + +You can view your executions history by opening the left menu, then selecting **Executions**. n8n opens the **Workflow Executions** modal. diff --git a/docs/workflows/index.md b/docs/workflows/index.md index 138b37e94..837c87480 100644 --- a/docs/workflows/index.md +++ b/docs/workflows/index.md @@ -1,4 +1,4 @@ -# Overview +# Workflows Learn about the key components of an automation in n8n: diff --git a/document-templates/app-nodes.md b/document-templates/app-nodes.md index d510987a7..a835682f9 100644 --- a/document-templates/app-nodes.md +++ b/document-templates/app-nodes.md @@ -31,17 +31,14 @@ _Briefly summarize the service. This should be one or two sentences, and can oft ## Related resources -Refer to [_Name's_ documentation]() for details about the operations. +Refer to [_Name's_ documentation]() for more information about the service. n8n provides a trigger node for _Name_. You can find the trigger node docs [here](). - -### Examples + +View [example workflows and related content](){:target=_blank .external-link} on n8n's website. -* _List of links_ -* _To blog posts_ -* _And integrations marketing pages_ +Refer to [_Name's_ documentation]() for details about the operations. -_Link to the credentials doc_ + +n8n provides an app node for _Name_. You can find the node docs [here](). -_Link to the related app node if it exists._ + ### Examples * _List of links_ diff --git a/draft/simplified-auth-release-note.md b/draft/simplified-auth-release-note.md deleted file mode 100644 index 3f06d5d75..000000000 --- a/draft/simplified-auth-release-note.md +++ /dev/null @@ -1,45 +0,0 @@ -## [TODO: in com nodes release] - -
- -#### Simplify authentication setup for node creators - -This release introduces a simpler way of handling authorization when building a node. All credentials should now contain an `authenticate` property that dictates how the credential is used in a request. -n8n has also simplified authentication types: instead of specifying an authentication type and using the correct interface, you can now set the type as `"generic"`, and use the `IAuthenticateGeneric` interface. - -You can use this approach for any authentication method where data is sent in the header, body, or query string. This includes methods like bearer and basic auth. You can't use this approach for more complex authentication types that require multiple calls, or for methods that don't pass authentication data. This includes OAuth. - -For an example of the new authentication syntax, refer to n8n's [Asana node](https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/credentials/AsanaApi.credentials.ts){:target=_blank .external-link}. - -```js -// in AsanaApi.credentials.ts -import { - IAuthenticateGeneric, - ICredentialType, - INodeProperties, -} from 'n8n-workflow'; - -export class AsanaApi implements ICredentialType { - name = 'asanaApi'; - displayName = 'Asana API'; - documentationUrl = 'asana'; - properties: INodeProperties[] = [ - { - displayName: 'Access Token', - name: 'accessToken', - type: 'string', - default: '', - }, - ]; - - authenticate: IAuthenticateGeneric = { - type: 'generic', - properties: { - headers: { - Authorization: '=Bearer {{$credentials.accessToken}}', - }, - }, - }; -} -``` -
\ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 7b7b8eba9..05d8d46b0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,5 @@ site_name: n8n Documentation +site_url: https://docs.n8n.io/ theme: name: material custom_dir: overrides @@ -11,11 +12,27 @@ theme: features: # https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-annotations - content.code.annotate + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#section-index-pages + - navigation.indexes # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=navigation+tabs#navigation-tabs - navigation.tabs - navigation.tabs.sticky # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=navigation+tabs#anchor-tracking - navigation.tracking +copyright: > + Change cookie settings +extra: + analytics: + provider: google + property: UA-146470481-3 + extra: + consent: + title: Cookie consent + description: >- + We use cookies to recognize your repeated visits and preferences, as well + as to measure the effectiveness of our documentation and whether users + find what they're searching for. With your consent, you're helping us to + make our documentation better.
Privacy policy # https://squidfunk.github.io/mkdocs-material/customization/?h=#additional-css extra_css: - _extra/css/extra.css @@ -44,6 +61,11 @@ markdown_extensions: linenums: true # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#superfences Superfences is required for several other features. Always enable. - pymdownx.superfences: + # https://squidfunk.github.io/mkdocs-material/reference/diagrams/ + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format # https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#preserve-tabs preserve_tabs: true - pymdownx.tasklist: @@ -67,50 +89,69 @@ nav: - Using n8n: - Welcome: index.md - Try it out: - - Overview: try-it-out/index.md + - try-it-out/index.md - A very quick quickstart: try-it-out/quickstart.md - A longer introduction: try-it-out/longer-introduction.md - - Editor UI: editor-ui.md - Understand workflows: - - Overview: workflows/index.md + - workflows/index.md - Workflows: workflows/workflows.md - Connections: workflows/connections.md - Nodes: workflows/nodes.md - Items: workflows/items.md - Sticky Notes: workflows/sticky-notes.md + - Executions: workflows/executions.md + - Manage credentials: + - credentials/index.md + - Create and edit: credentials/add-edit-credentials.md + - Credential sharing: credentials/credential-sharing.md - Flow logic: - - Overview: flow-logic/index.md + - flow-logic/index.md - Merging: flow-logic/merging.md - Looping: flow-logic/looping.md - Error handling: flow-logic/error-handling.md - Data: - - Overview: data/index.md + - data/index.md - Data structure: data/data-structure.md - Transforming data: data/transforming-data.md - - Using code: data/code.md - - Data mapping: data/data-mapping.md + - Process data using code: data/code.md + - Data mapping: + - data/data-mapping/index.md + - Data mapping in the UI: data/data-mapping/data-mapping-ui.md + - Data item linking: + - data/data-mapping/data-item-linking/index.md + - Item linking concepts: data/data-mapping/data-item-linking/item-linking-concepts.md + - Item linking in the Code node: data/data-mapping/data-item-linking/item-linking-code-node.md + - Item linking errors: data/data-mapping/data-item-linking/item-linking-errors.md + - Item linking for node creators: data/data-mapping/data-item-linking/item-linking-node-building.md - Data pinning: data/data-pinning.md - Data editing: data/data-editing.md - - Code examples: - - Overview: code-examples/index.md - - Expressions: - - Overview: code-examples/expressions/index.md - - Methods: code-examples/expressions/methods.md - - Variables: code-examples/expressions/variables.md + - Expressions and JavaScript: + - code-examples/index.md + - Built in methods and variables reference: code-examples/methods-variables-reference.md + - Built-in methods and variables examples: + - code-examples/methods-variables-examples/index.md + - evaluateExpression: code-examples/methods-variables-examples/evaluate-expression.md + - execution: code-examples/methods-variables-examples/execution.md + - getWorkflowStaticData: code-examples/methods-variables-examples/get-workflow-static-data.md + - (node-name).item: code-examples/methods-variables-examples/node.md + - (node-name).all: code-examples/methods-variables-examples/all.md + - runIndex: code-examples/methods-variables-examples/run-index.md + - workflow: code-examples/methods-variables-examples/workflow.md + - Expressions examples: + - code-examples/expressions/index.md - Date and time with Luxon: code-examples/expressions/luxon.md - JSON with JMESPath: code-examples/expressions/jmespath.md - - JavaScript for workflows: - - Overview: code-examples/javascript-functions/index.md - - Methods: code-examples/javascript-functions/methods.md - - Variables: code-examples/javascript-functions/variables.md + - JavaScript examples: + - code-examples/javascript-functions/index.md - Date and time with Luxon: code-examples/javascript-functions/luxon.md - JSON with JMESPath: code-examples/javascript-functions/jmespath.md - Get number of items returned by last node: code-examples/javascript-functions/number-items-last-node.md - Split binary file data into individual items: code-examples/javascript-functions/split-binary-file-data.md - Get the binary data buffer: code-examples/javascript-functions/get-binary-data-buffer.md - Check incoming data: code-examples/javascript-functions/check-incoming-data.md + - Using console.log: code-examples/console-log.md - Reference: - - Overview: reference/index.md + - reference/index.md - Release notes: reference/release-notes.md - CLI commands: reference/cli-commands.md - Keyboard shortcuts: reference/keyboard-shortcuts.md @@ -118,16 +159,251 @@ nav: - License: reference/license.md - Data collection: reference/data-collection.md - Integrations: - - Overview: integrations/index.md + - integrations/index.md - Built-in nodes: - - Overview: integrations/builtin/index.md + - integrations/builtin/index.md - Core nodes: integrations/builtin/core-nodes/ - App nodes: integrations/builtin/app-nodes/ - Trigger nodes: integrations/builtin/trigger-nodes/ - - Credentials: integrations/builtin/credentials/ + - Credentials: + - integrations/builtin/credentials/index.md + - integrations/builtin/credentials/actionnetwork.md + - integrations/builtin/credentials/activecampaign.md + - integrations/builtin/credentials/acuityscheduling.md + - integrations/builtin/credentials/adalo.md + - integrations/builtin/credentials/affinity.md + - integrations/builtin/credentials/agilecrm.md + - integrations/builtin/credentials/airtable.md + - integrations/builtin/credentials/amqp.md + - integrations/builtin/credentials/apitemplateio.md + - integrations/builtin/credentials/asana.md + - integrations/builtin/credentials/automizy.md + - integrations/builtin/credentials/autopilot.md + - integrations/builtin/credentials/aws.md + - integrations/builtin/credentials/bamboohr.md + - integrations/builtin/credentials/bannerbear.md + - integrations/builtin/credentials/baserow.md + - integrations/builtin/credentials/beeminder.md + - integrations/builtin/credentials/bitbucket.md + - integrations/builtin/credentials/bitly.md + - integrations/builtin/credentials/bitwarden.md + - integrations/builtin/credentials/box.md + - integrations/builtin/credentials/brandfetch.md + - integrations/builtin/credentials/bubble.md + - integrations/builtin/credentials/cal.md + - integrations/builtin/credentials/calendly.md + - integrations/builtin/credentials/chargebee.md + - integrations/builtin/credentials/circleci.md + - integrations/builtin/credentials/ciscowebex.md + - integrations/builtin/credentials/citrixadc.md + - integrations/builtin/credentials/clearbit.md + - integrations/builtin/credentials/clickup.md + - integrations/builtin/credentials/clockify.md + - integrations/builtin/credentials/cloudflare.md + - integrations/builtin/credentials/cockpit.md + - integrations/builtin/credentials/coda.md + - integrations/builtin/credentials/contentful.md + - integrations/builtin/credentials/convertkit.md + - integrations/builtin/credentials/copper.md + - integrations/builtin/credentials/cortex.md + - integrations/builtin/credentials/cratedb.md + - integrations/builtin/credentials/customerio.md + - integrations/builtin/credentials/deepl.md + - integrations/builtin/credentials/demio.md + - integrations/builtin/credentials/dhl.md + - integrations/builtin/credentials/discord.md + - integrations/builtin/credentials/discourse.md + - integrations/builtin/credentials/disqus.md + - integrations/builtin/credentials/drift.md + - integrations/builtin/credentials/dropbox.md + - integrations/builtin/credentials/dropcontact.md + - integrations/builtin/credentials/egoi.md + - integrations/builtin/credentials/elasticsearch.md + - integrations/builtin/credentials/elasticsecurity.md + - integrations/builtin/credentials/emelia.md + - integrations/builtin/credentials/erpnext.md + - integrations/builtin/credentials/eventbrite.md + - integrations/builtin/credentials/facebookapp.md + - integrations/builtin/credentials/facebookgraph.md + - integrations/builtin/credentials/figma.md + - integrations/builtin/credentials/filemaker.md + - integrations/builtin/credentials/flow.md + - integrations/builtin/credentials/formiotrigger.md + - integrations/builtin/credentials/formstacktrigger.md + - integrations/builtin/credentials/freshdesk.md + - integrations/builtin/credentials/freshservice.md + - integrations/builtin/credentials/freshworkscrm.md + - integrations/builtin/credentials/ftp.md + - integrations/builtin/credentials/getresponse.md + - integrations/builtin/credentials/ghost.md + - integrations/builtin/credentials/git.md + - integrations/builtin/credentials/github.md + - integrations/builtin/credentials/gitlab.md + - Google: + - integrations/builtin/credentials/google/index.md + - integrations/builtin/credentials/google/oauth-single-service.md + - integrations/builtin/credentials/google/oauth-generic.md + - integrations/builtin/credentials/google/service-account.md + - integrations/builtin/credentials/gotify.md + - integrations/builtin/credentials/gotowebinar.md + - integrations/builtin/credentials/grafana.md + - integrations/builtin/credentials/grist.md + - integrations/builtin/credentials/gumroad.md + - integrations/builtin/credentials/halopsa.md + - integrations/builtin/credentials/harvest.md + - integrations/builtin/credentials/helpscout.md + - integrations/builtin/credentials/highlevel.md + - integrations/builtin/credentials/homeassistant.md + - integrations/builtin/credentials/httprequest.md + - integrations/builtin/credentials/hubspot.md + - integrations/builtin/credentials/humanticai.md + - integrations/builtin/credentials/hunter.md + - integrations/builtin/credentials/imap.md + - integrations/builtin/credentials/intercom.md + - integrations/builtin/credentials/invoiceninja.md + - integrations/builtin/credentials/iterable.md + - integrations/builtin/credentials/jenkins.md + - integrations/builtin/credentials/jira.md + - integrations/builtin/credentials/jotform.md + - integrations/builtin/credentials/kafka.md + - integrations/builtin/credentials/keap.md + - integrations/builtin/credentials/kitemaker.md + - integrations/builtin/credentials/kobotoolbox.md + - integrations/builtin/credentials/lemlist.md + - integrations/builtin/credentials/line.md + - integrations/builtin/credentials/linear.md + - integrations/builtin/credentials/lingvanex.md + - integrations/builtin/credentials/linkedin.md + - integrations/builtin/credentials/magento2.md + - integrations/builtin/credentials/mailcheck.md + - integrations/builtin/credentials/mailchimp.md + - integrations/builtin/credentials/mailerlite.md + - integrations/builtin/credentials/mailgun.md + - integrations/builtin/credentials/mailjet.md + - integrations/builtin/credentials/mandrill.md + - integrations/builtin/credentials/marketstack.md + - integrations/builtin/credentials/matrix.md + - integrations/builtin/credentials/mattermost.md + - integrations/builtin/credentials/mautic.md + - integrations/builtin/credentials/medium.md + - integrations/builtin/credentials/messagebird.md + - integrations/builtin/credentials/metabase.md + - integrations/builtin/credentials/microsoft.md + - integrations/builtin/credentials/microsoftsql.md + - integrations/builtin/credentials/mindee.md + - integrations/builtin/credentials/misp.md + - integrations/builtin/credentials/mocean.md + - integrations/builtin/credentials/mondaycom.md + - integrations/builtin/credentials/mongodb.md + - integrations/builtin/credentials/monicacrm.md + - integrations/builtin/credentials/mqtt.md + - integrations/builtin/credentials/msg91.md + - integrations/builtin/credentials/mysql.md + - integrations/builtin/credentials/nasa.md + - integrations/builtin/credentials/netlify.md + - integrations/builtin/credentials/nextcloud.md + - integrations/builtin/credentials/nocodb.md + - integrations/builtin/credentials/notion.md + - integrations/builtin/credentials/odoo.md + - integrations/builtin/credentials/onesimpleapi.md + - integrations/builtin/credentials/onfleet.md + - integrations/builtin/credentials/openweathermap.md + - integrations/builtin/credentials/orbit.md + - integrations/builtin/credentials/oura.md + - integrations/builtin/credentials/paddle.md + - integrations/builtin/credentials/pagerduty.md + - integrations/builtin/credentials/paypal.md + - integrations/builtin/credentials/peekalink.md + - integrations/builtin/credentials/phantombuster.md + - integrations/builtin/credentials/philipshue.md + - integrations/builtin/credentials/pipedrive.md + - integrations/builtin/credentials/plivo.md + - integrations/builtin/credentials/postgres.md + - integrations/builtin/credentials/posthog.md + - integrations/builtin/credentials/postmark.md + - integrations/builtin/credentials/profitwell.md + - integrations/builtin/credentials/pushbullet.md + - integrations/builtin/credentials/pushcut.md + - integrations/builtin/credentials/pushover.md + - integrations/builtin/credentials/questdb.md + - integrations/builtin/credentials/quickbase.md + - integrations/builtin/credentials/quickbooks.md + - integrations/builtin/credentials/rabbitmq.md + - integrations/builtin/credentials/raindrop.md + - integrations/builtin/credentials/reddit.md + - integrations/builtin/credentials/redis.md + - integrations/builtin/credentials/rocketchat.md + - integrations/builtin/credentials/rundeck.md + - integrations/builtin/credentials/s3.md + - integrations/builtin/credentials/salesforce.md + - integrations/builtin/credentials/salesmate.md + - integrations/builtin/credentials/seatable.md + - integrations/builtin/credentials/securityscorecard.md + - integrations/builtin/credentials/segment.md + - integrations/builtin/credentials/sendemail.md + - integrations/builtin/credentials/sendgrid.md + - integrations/builtin/credentials/sendinblue.md + - integrations/builtin/credentials/sendy.md + - integrations/builtin/credentials/sentryio.md + - integrations/builtin/credentials/servicenow.md + - integrations/builtin/credentials/shopify.md + - integrations/builtin/credentials/signl4.md + - integrations/builtin/credentials/slack.md + - integrations/builtin/credentials/sms77.md + - integrations/builtin/credentials/snowflake.md + - integrations/builtin/credentials/splunk.md + - integrations/builtin/credentials/spontit.md + - integrations/builtin/credentials/spotify.md + - integrations/builtin/credentials/ssh.md + - integrations/builtin/credentials/stackby.md + - integrations/builtin/credentials/storyblok.md + - integrations/builtin/credentials/strapi.md + - integrations/builtin/credentials/strava.md + - integrations/builtin/credentials/stripe.md + - integrations/builtin/credentials/supabase.md + - integrations/builtin/credentials/surveymonkey.md + - integrations/builtin/credentials/syncromsp.md + - integrations/builtin/credentials/taiga.md + - integrations/builtin/credentials/tapfiliate.md + - integrations/builtin/credentials/telegram.md + - integrations/builtin/credentials/thehive.md + - integrations/builtin/credentials/timescaledb.md + - integrations/builtin/credentials/todoist.md + - integrations/builtin/credentials/toggl.md + - integrations/builtin/credentials/travisci.md + - integrations/builtin/credentials/trello.md + - integrations/builtin/credentials/twake.md + - integrations/builtin/credentials/twilio.md + - integrations/builtin/credentials/twist.md + - integrations/builtin/credentials/twitter.md + - integrations/builtin/credentials/typeform.md + - integrations/builtin/credentials/unleashedsoftware.md + - integrations/builtin/credentials/uplead.md + - integrations/builtin/credentials/uproc.md + - integrations/builtin/credentials/uptimerobot.md + - integrations/builtin/credentials/urlscanio.md + - integrations/builtin/credentials/venafitlsprotectcloud.md + - integrations/builtin/credentials/venafitlsprotectdatacenter.md + - integrations/builtin/credentials/vero.md + - integrations/builtin/credentials/vonage.md + - integrations/builtin/credentials/webflow.md + - integrations/builtin/credentials/wekan.md + - integrations/builtin/credentials/whatsapp.md + - integrations/builtin/credentials/wise.md + - integrations/builtin/credentials/woocommerce.md + - integrations/builtin/credentials/wordpress.md + - integrations/builtin/credentials/workable.md + - integrations/builtin/credentials/wufoo.md + - integrations/builtin/credentials/xero.md + - integrations/builtin/credentials/yourls.md + - integrations/builtin/credentials/zammad.md + - integrations/builtin/credentials/zendesk.md + - integrations/builtin/credentials/zoho.md + - integrations/builtin/credentials/zoom.md + - integrations/builtin/credentials/zulip.md - Custom API actions for existing nodes: integrations/custom-operations.md - Community nodes: - - Overview: integrations/community-nodes/index.md + - integrations/community-nodes/index.md - Installation and management: integrations/community-nodes/installation.md - Risks: integrations/community-nodes/risks.md - Blocklist: integrations/community-nodes/blocklist.md @@ -135,19 +411,19 @@ nav: - Troubleshooting: integrations/community-nodes/troubleshooting.md - Building community nodes: integrations/community-nodes/build-community-nodes.md - Creating nodes: - - Overview: integrations/creating-nodes/index.md + - integrations/creating-nodes/index.md - Plan your node: - - Overview: integrations/creating-nodes/plan/index.md + - integrations/creating-nodes/plan/index.md - Choose a node building style: integrations/creating-nodes/plan/choose-node-method.md - Node UI design: integrations/creating-nodes/plan/node-ui-design.md - Choose node file structure: integrations/creating-nodes/build/reference/node-file-structure.md - Build your node: - - Overview: integrations/creating-nodes/build/index.md + - integrations/creating-nodes/build/index.md - Set up your development environment: integrations/creating-nodes/build/node-development-environment.md - "Tutorial: Build a declarative-style node": integrations/creating-nodes/build/declarative-style-node.md - "Tutorial: Build a programmatic-style node": integrations/creating-nodes/build/programmatic-style-node.md - Reference: - - Overview: integrations/creating-nodes/build/reference/index.md + - integrations/creating-nodes/build/reference/index.md - Node UI elements: integrations/creating-nodes/build/reference/ui-elements.md - Code standards: integrations/creating-nodes/build/reference/code-standards.md - Versioning: integrations/creating-nodes/build/reference/node-versioning.md @@ -156,21 +432,21 @@ nav: - 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 - - Paired items: integrations/creating-nodes/build/reference/paired-items.md + - Item linking: integrations/creating-nodes/build/reference/paired-items.md - Test your node: - - Overview: integrations/creating-nodes/test/index.md + - integrations/creating-nodes/test/index.md - Run your node locally: integrations/creating-nodes/test/run-node-locally.md - Node linter: integrations/creating-nodes/test/node-linter.md - Troubleshooting: integrations/creating-nodes/test/troubleshooting-node-development.md - Deploy your node: - - Overview: integrations/creating-nodes/deploy/index.md + - integrations/creating-nodes/deploy/index.md - Submit community nodes: integrations/creating-nodes/deploy/submit-community-nodes.md - Install private nodes: integrations/creating-nodes/deploy/install-private-nodes.md - Hosting n8n: - - Overview: hosting/index.md + - hosting/index.md - Installation and hosting options: hosting/options.md - Installation: - - Overview: hosting/installation/index.md + - hosting/installation/index.md - Desktop app: hosting/installation/desktop-app.md - npm: hosting/installation/npm.md - Docker: hosting/installation/docker.md @@ -181,43 +457,46 @@ nav: - Security: hosting/security.md - Logging: hosting/logging.md - Server setups: - - Overview: hosting/server-setups/index.md + - hosting/server-setups/index.md - Docker Compose: hosting/server-setups/docker-compose.md - Caddy: hosting/server-setups/caddy.md - Digital Ocean: hosting/server-setups/digital-ocean.md - Hetzner: hosting/server-setups/hetzner.md + - Amazon Web Services: hosting/server-setups/aws.md + - Google Cloud: hosting/server-setups/google-cloud.md - Databases: - - Overview: hosting/databases/index.md + - hosting/databases/index.md - Supported databases and settings: hosting/databases/supported-databases-settings.md - Database structure: hosting/databases/structure.md - Updating: - - Overview: hosting/updating/index.md + - hosting/updating/index.md - npm: hosting/updating/npm.md - Docker: hosting/updating/docker.md - Desktop app: hosting/updating/desktop.md - Cloud: hosting/updating/cloud.md - Scaling: - - Overview: hosting/scaling/index.md + - hosting/scaling/index.md - Execution data: hosting/scaling/execution-data.md - Execution modes and processes: hosting/scaling/execution-modes-processes.md - Configuring queue mode: hosting/scaling/queue-mode.md - API: - - The n8n public API: api/index.md + - api/index.md - Authentication: api/authentication.md - Pagination: api/pagination.md - Using the API playground: api/using-api-playground.md - API reference: api/api-reference.md - Embed: - - n8n Embed: embed/index.md + - embed/index.md - Prerequisites: embed/prerequisites.md - Deployment: embed/deployment.md - Configuration: embed/configuration.md - Workflow management: embed/managing-workflows.md - Workflows templates: embed/workflow-templates.md + - White Labelling: embed/white-labelling.md - Courses: - - Overview: courses/index.md + - courses/index.md - Level one: - - Overview: courses/level-one/index.md + - courses/level-one/index.md - Navigating the editor UI: courses/level-one/chapter-1.md - Building a mini-workflow: courses/level-one/chapter-2.md - Automating a (real-world) use case: courses/level-one/chapter-3.md @@ -234,7 +513,7 @@ nav: - Exporting and importing workflows: courses/level-one/chapter-6.md - Test your knowledge: courses/level-one/chapter-7.md - Level two: - - Overview: courses/level-two/index.md + - courses/level-two/index.md - Understanding the data structure: courses/level-two/chapter-1.md - Processing different data types: courses/level-two/chapter-2.md - Merging and splitting data: courses/level-two/chapter-3.md diff --git a/netlify.toml b/netlify.toml index 7cc1d448a..de453e9e7 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,3 +1,3 @@ [build] - command = "pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@8.3.2-insiders-4.17.2 && mkdocs build" + command = "pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@8.5.6-insiders-4.25.1 && mkdocs build" publish = "site" diff --git a/overrides/404.html b/overrides/404.html index f91e42956..13b7a583a 100644 --- a/overrides/404.html +++ b/overrides/404.html @@ -31,8 +31,14 @@ "/#what-is-n8n": "/", "/getting-started/tutorials.html#blogposts": "https://n8n.io/blog/tag/tutorial/", "/#/server-setup": "/hosting/server-setups/", - "/code-examples/expressions/expressions.html": "/code-examples/expressions/" - // 404s reports + "/code-examples/expressions/expressions.html": "/code-examples/expressions/", + // Editor UI split + "/editor-ui/workflows": "/workflows/", + "/editor-ui/credentials": "/credentials/", + "/editor-ui/executions": "/workflows/executions/", + "/editor-ui/admin-panel": "/hosting/updating/cloud/", + // New code node + "/hosting/configuration/#use-built-in-and-external-modules-in-function-nodes": "/hosting/configuration/#use-built-in-and-external-modules-in-the-code-node" }; diff --git a/overrides/main.html b/overrides/main.html deleted file mode 100644 index d1cf04a0d..000000000 --- a/overrides/main.html +++ /dev/null @@ -1,29 +0,0 @@ -{% extends "base.html" %} - -{% block extrahead %} - - - - - - -{% endblock %} - - diff --git a/requirements.txt b/requirements.txt index 0543e9ce6..05c3ef2d0 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,2 @@ -essentials-openapi==1.0.2 mkdocs-literate-nav==0.4.1 -mkdocs-render-swagger-plugin==0.0.3 neoteroi-mkdocs==0.0.5 diff --git a/styles/Vocab/default/accept.txt b/styles/Vocab/default/accept.txt index 30f7b6f77..b16896e8f 100644 --- a/styles/Vocab/default/accept.txt +++ b/styles/Vocab/default/accept.txt @@ -1,3 +1,4 @@ +Adalo Asana Axios backend @@ -5,13 +6,18 @@ Beeminder Boolean boolean Caddy +Citrix Clockify Cron Dockerfile +eksctl Enum enum +Fargate +Firestore GIMP invalid +kubectl Kafka Lemlist Luxon @@ -27,6 +33,9 @@ onboarding Pipedrive Postbin Postgres +Realtime +Serverless +serverless Shopify shopify There are @@ -34,5 +43,8 @@ Tooltip tooltip Trello Twilio +URI +URIs URL +Venafi Vuex