How to reuse a group of steps (custom nodes)

A custom node in TeleportHQ is a group of workflow steps you build once and use in many workflows, like a function. Create it in the Custom Nodes section at the bottom of the Workflows panel, add its steps, then add a Custom Node step to any workflow and pick it. When you change the custom node, every workflow that uses it gets the change.

Before you start#

• Custom nodes are part of workflows, a web app feature. See What are workflows?.
• Good candidates are steps you repeat, for example "look up a customer by email and create them if they don't exist", used by an order form, a booking form and a newsletter form.

Steps#

1. Create the custom node#

1. In the left sidebar, click Workflows.
2. In the lower Custom Nodes section, click + (tooltip Add Custom Node). If there are none yet, click Add custom node.
3. A custom node called Untitled Custom Node opens in the editor.
4. In the header, click the name (tooltip Edit custom node name) and type a clear name, for example Find or create customer.

2. Add its steps#

1. On the empty canvas, click Add your first node.
2. In the Add Node menu, point at Data and click Select Data, then set it up.
3. Click the round + (Add node) below the last box to add the next steps, for example an If Statement and a Create Item.

Custom nodes have no trigger. They run when a workflow reaches them, and they receive all the data (context) from that workflow.

3. Describe it#

1. In the Custom Nodes section, click the More options button on the custom node's card.
2. Click Open details.
3. In Custom Node Details, type a Description, or click Generate description using AI. A description helps the AI Assistant understand what the custom node does.

4. Use it in a workflow#

1. Open a workflow. Point at the step after which the custom node should run and click the round + (Add node) below it.
2. In the Add Node menu, point at General and click Custom Node. You can also type the custom node's name in Search nodes...: General stays in the list.
3. In the right panel, under Custom Node, choose Find or create customer.
4. Under Parameters, click Add Parameter and enter a name and value to pass in, for example email with the form's email from the Context panel.
5. To edit the custom node from here, click Go to Custom Workflow Node.

5. Read the parameters inside the custom node#

Inside the custom node, a Custom JavaScript step reads each parameter by its name, for example params.email. When a Custom JavaScript step in the custom node already uses a name such as params.email, the Custom Node step shows "1 parameter detected from custom JS node": click it, then Auto-populate Missing Parameters to add that parameter for you. Other steps inside the custom node use the data of the workflow that runs it.

Check that it worked#

• In the workflow, the Custom Node step shows how many nodes the custom node has and in how many places it's used ("Used in N place(s)").
• Later steps in the workflow can use the custom node's result from the Context panel.

Troubleshooting#

"No custom nodes available. Create a custom node first from the Workflows sidebar to use it here." There are no custom nodes in the project yet. Create one as in part 1.

Deleting a custom node warns that it "is currently being used in N workflow(s) or custom node(s)" If you click Delete Custom Node, every Custom Node step that uses it is reset to its default state and those workflows stop running its logic. This can't be undone. To keep the logic, cancel and replace those steps first.

A custom node's browser steps don't work in a scheduled or webhook workflow Scheduled (Cron) and Webhook Received workflows run on the server, where there's no visitor's page. Browser-only steps inside a custom node, such as Show Toast or Set Element Text, can't do their job there. Use custom nodes with server steps only, such as data, email and HTTP steps, in those workflows. See the Workflow triggers and steps reference.

Good to know#

• A custom node can be used inside other custom nodes.
• When every branch of a custom node ends in a step that must be last, such as Go to Page, the custom node can only be the last step of a workflow: "Every branch inside this custom node ends in a terminal action, so it can only be placed as the final node in a workflow".
• The AI Assistant tab also works inside a custom node: describe the reusable operation, for example "take an email, find the customer and return their name". See How to build a workflow with AI.
• The Test runs tab of a custom node lists the step tests you ran inside it. See How to test a workflow step.
• There is no plan limit on the number of custom nodes in the editor.