Understanding Custom Nodes

Overview

A custom node is a workflow you've made available as a node. Once a workflow is a node, you and your team can add it to any other workflow from the node library, the same way you add a gaiia node. In this article, we'll be covering what custom nodes are, how to create them, and what to know before you change one.

Custom nodes help you standardize a process once and reuse it everywhere. Your team builds workflows faster, and every workflow that uses the node behaves the same way.

Understand how custom nodes work

Think of a workflow as a recipe. A custom node is that recipe added to the menu as a single item. Anyone building a workflow can use it without knowing the steps inside.

The recipe doesn't go away. Every custom node is backed by a regular workflow that you can open, test, and edit. When a workflow uses the node, it passes the inputs to the backing workflow, waits for it to run, and receives its output.

• The node's inputs come from the backing workflow's trigger input schema.
• The node's output is the backing workflow's output.
• The node takes the name of the backing workflow.

Custom nodes are a good fit for HTTP-based integrations. You can store an API key as a secret and reference it from the backing workflow, so the people who use the node never handle the key. See Building your own integration with a custom node for a walkthrough.

Check which workflows can become nodes

A workflow can become a custom node when it meets all of these requirements:

• It uses a Manual trigger.
• It has no object type.
• It has a published version.

A workflow can back only one node.

Describe what your node returns

Add an output schema to describe the data your workflow returns. Anyone who uses the node then gets accurate field suggestions for its output in later steps.

1. Open the workflow and select the End node.
2. In the side panel, set Type of output to JSON.
3. Click Add output schema.
4. Enter a JSON schema that describes the fields you return.

To remove the schema, click the trash icon next to it.

The output schema is optional. gaiia doesn't check the workflow's output against it when the workflow runs, but it is what gaiia uses to protect people who depend on your node. Without one, gaiia can't tell when a change removes an output field. See Change a node safely.

Load dropdown options from a workflow

A node input can show a dropdown whose options come from another workflow. Because a custom node's inputs come from the backing workflow's trigger input schema, you set this up in the trigger input schema. The options load when someone opens the dropdown, and an input defined as an array lets them select more than one option.

For the schema setup, see Configuring the workflow trigger input schema.

Convert a workflow to a node

Use this option when you're already in the workflow and realize it should be reusable.

1. Open the workflow.
2. Click the … menu next to the workflow name.
3. Select Convert to node.
4. In the Convert this workflow to a node? dialog, confirm.

If Convert to node is greyed out, hover over it to see why. Only workflows with a manual trigger and no object types can be converted.

The workflow keeps working as a workflow. The node appears in the node library under the workflow's name.

Create a node from selected nodes

Use this option to turn part of a workflow into a reusable node.

1. In the builder, select the nodes you want to reuse.
2. Right-click the selection.
3. Select Create new node.
4. Name the node and confirm.
5. Publish the workflow to keep the change.

gaiia builds a new workflow from your selection and replaces the selected nodes with the new node.

Create a node from an existing workflow

1. Go to Workflows > Custom nodes.
2. Click Create node.
3. Search for a workflow and select it.
4. Click Create node.

The original workflow stays unchanged. The Custom nodes list shows all your nodes, with their deployments and executions.

Use a custom node in a workflow

1. In the Graph View, click the + icon where you want to add the node.
2. Open your organization's section in the node library, then open the Custom nodes folder.
3. Select the node.
4. Fill in the node's inputs in the side panel.

Integrations that are private to your organization also appear in your organization's section of the node library.

To see how a node works, select it in the workflow and click Go to full node definition.

Change a node safely

Because the workflow behind a node is a regular workflow, editing it changes the node everywhere it's used. This is how you fix or improve a process once for every workflow that depends on it.

To protect the workflows that use the node, gaiia blocks a publish that would break the node's contract. A publish is blocked when you:

• Change the trigger type away from Manual, or add an object type to the trigger.
• Remove a required input field, or a required output field from the output schema.
• Change the type of a required input field.
• Make an input required, unless every workflow that uses the node already sets it.

The error names the field and lists the affected workflows. To remove or retype a required field, make it optional first, then change or remove it. To add a new required input, add it as optional first, or make sure every workflow using the node sets it.

gaiia also blocks a publish that creates a circular setup, where node A uses node B, which uses node A.

Changes to how the workflow behaves take effect for every workflow using the node as soon as you publish. Test changes before you publish them.

Find your node workflows

Workflows that back a node are hidden from the workflow list by default, so they don't crowd the workflows you launch and manage.

1. Go to Workflows.
2. Open the filter popover.
3. Turn on Show workflow nodes.

Integration workflows that back a node also require Show integration workflows to be on.

A workflow that is a node shows a Node indicator next to its name. Click it to open the This workflow is also a node panel, which lists the workflows the node is deployed in under Deployed in workflows. A node that no workflow uses yet shows Not deployed in any workflow yet.

Remove a node

Removing a node doesn't delete its workflow. The workflow returns to the workflow list with its versions and executions intact.

1. Open the workflow that backs the node.
2. Click the Node indicator next to the workflow name.
3. In the This workflow is also a node panel, click Remove as node.
4. Confirm in the Remove as reusable node? dialog.

You can't remove a node while other workflows use it. Remove as node stays greyed out until you remove the node from every workflow listed under Deployed in workflows.