Design Custom Nodes with the Visual Node Builder

Use the Visual Node Builder to configure the interface of a reusable action node. This page is a practical guide to the builder and, in particular, the configuration inspector on the right. For the design model behind variants, lines, fields, and element packs, read Logic Node Overview. To place and configure a finished node inside a request, read Logic Flow Builder.

Open Node Builder from the main navigation, a custom-node AI plan, an existing template, or a clone. Define the visual contract here before implementing its tags in Code Builder.

Follow this order for a new node:

1. Configure Identity & Appearance.
2. Create the node's variants and select the variant you want to edit.
3. Add configuration lines in the order users should complete them.
4. Add Text Label, Input, or Select fields to each line.
5. Define the variant's Base Elements: inputs, outputs, logic flows, and error handlers.
6. Add custom element packs for elements that should appear only in certain cases.
7. Add conditions, then attach one or more behaviors to each condition.
8. Create line or element-pack instances only when a behavior needs an alternative configuration.
9. Review the live preview and issue list, then continue to Code Builder.

Identity and Appearance

Select Node Settings > Identity & Appearance in the left sidebar. The right sidebar opens Node Properties.

Identity

Appearance

The Variants list in this same inspector can add, open, delete, and drag variants into a new order. The Documentation section previews the usage Markdown generated from the current node and can download it as a .md file.

Variants

A variant is one selectable operating mode of the node. Use one variant if the configuration and elements never change at the highest level. Add variants when users must choose between clearly different modes, such as Read, Create, Update, and Delete.

Select a variant from the left sidebar or from Node Properties > Variants. The selected variant becomes active in the preview, and all following lines, conditions, and packs belong to it.

Order variants as users should encounter them. Select the most common variant while reviewing the preview, but inspect every variant before publishing.

Configuration Lines

Lines are the rows displayed inside a node. A line combines a purpose, a visibility rule, and an ordered list of fields.

To add one, select the active variant and choose Add line from either Configuration Lines in the left sidebar or the variant inspector. Select the new line to open Line Configuration.

Start with the line properties in the right sidebar. These settings define the line's name, purpose, visibility behavior, and presentation.

Drag fields in the Fields list to control their left-to-right order. Drag lines in the variant inspector to control their top-to-bottom order.

When Line Type is Generic Object, additional settings appear for inherited attributes and relationships.

Generic Object is the only line type that can be tracked as Attribute in a condition. Attribute conditions evaluate once for each generated attribute.

Fields

Select a line and use the three add buttons in Fields. A line supports exactly these field kinds:

Field IDs are generated and kept stable when labels change because conditions, default-value references, and Code Builder tags depend on them. The issue button reports duplicate field IDs across the node.

Text Label

Select the label field and enter its Content. Use short connector text; the line name and description already provide the longer explanation.

Input Field

Select an input to configure its label, widget, placeholder, accepted type, and default value.

The Type Constraint validates values connected or referenced by the field. The selector includes String, Number, Integer, Float, Boolean, UUID, Date, DateTime, Text, JSON, File, Any, Object (Parent), Object (Child), Dynamic, Same as field, workspace classes, and workspace enums. Use the array toggle when the field expects a list of the selected type.

Choosing a concrete constraint also adjusts the widget to the closest suitable input type. For example, Number selects the number widget and Boolean selects the toggle.

Select Field

Select fields can contain a fixed list or derive their options from the active workspace.

Available relationship filters for Workspace Objects and Object Attributes are Association, Composition, Aggregation, Realization, and Dependency. Multiplicity filtering appears when Association, Composition, or Aggregation is selected and supports 1:1, 1:*, M:N, and :. Leaving every relation type or multiplicity enabled stores no extra restriction.

For dependent selects, place the Workspace Objects field before the Object Attributes field, then point the attribute field to it. This gives the preview and Logic Flow node enough context to populate the attribute list.

Default Values for Fields

Input and Select fields share the Default Value From editor.

A Select accepts environment and input tags only when it is single-select and Custom Input is enabled. Otherwise choose a listed option or another compatible field.

Element Packs

An element pack groups the canvas-facing parts of a variant: inputs, outputs, logic flows, and error handlers. Every variant has Base Elements, which are applied automatically. A custom pack is a prepared group that a condition behavior can show, hide, append, or replace with an instance.

Select Element Packs > Base Elements or add a custom pack with the plus button. All pack configuration appears in one right-sidebar panel; selecting Inputs, Outputs, Logic Flows, or Error Handlers in the left tree scrolls directly to that section.

Pack Settings

Inputs

Inputs are values received from a request or an earlier action in Logic Flow. Select Inputs, choose Add inputs, then configure each row.

Use the narrowest correct type. Every input referenced by a field's From Input default must be connected when the finished node is used.

Outputs

Outputs are values produced for later actions or request outputs. They use the same controls and type list as inputs.

Choose a meaningful, stable output name and the type downstream nodes should receive. Use Dynamic with an Object Attributes pointer when the output type follows a selected attribute. Set an output to Optional when it should be available through suggestions instead of appearing on every node instance. Enable User Can Add only when arbitrary additional outputs are valid for the implementation.

Changing a published output name or type can invalidate existing connections. Treat it as a contract change and update the Code Builder implementation before republishing.

Logic Flows

A Logic Flow element is a named execution branch exposed by the node. This section defines the branch handle; it does not build the actions inside that branch.

Error Handlers

Error handlers define expected failure exits. Add one handler for each failure that callers or later logic need to distinguish.

The builder defines the available error contract. The Code Builder determines when the implementation raises or maps each error.

Conditions and Behaviors

Conditions answer when the interface should change. Behaviors answer what changes. Build the target line, pack, and any required instances first so that they are available in the condition inspector.

Conditions

Add a condition with the plus button beside Conditions in the left sidebar. Select it to open Condition Rule in the right sidebar.

1. Enter a unique Condition Name.
2. In Line Visualisation, select the condition chip you want to edit.
3. Choose What to track and the specific field or line.
4. Choose an operator.
5. When the operator needs a comparison, choose Custom or Field as the value source.
6. Add conditions or nested groups and choose AND or OR for each group.
7. Add one or more behaviors under Then (Behaviors).

Is Empty, Is Not Empty, Appearing, and Not Appearing need no comparison value. For other operators, Custom compares against a literal or selected option, while Field compares against another existing field. Is In and multi-select comparisons accept more than one custom value.

Use nested groups for expressions such as (provider = Stripe AND retries > 0) OR fallback is appearing. Keep rules small and name them after the result they control.

Behaviors

Each condition can run multiple behaviors. Choose Add behavior, then select the target category, action, and exact line, pack, instance, or override.

Select Configure Instance to open the chosen instance without losing the path back to the condition. A condition can combine, for example, a Line Action that shows authentication settings and an Element Action that adds authentication outputs.

Instances

An instance starts as a copy of a line or element pack. It is an alternative configuration used by Override via Instance; it is not another item shown automatically.

Instances are copied at creation time. Later changes to the base do not automatically merge into existing instances, so review them after editing the original. Give every instance a name that describes the condition in which it is used, such as Paginated Result or Authenticated Input.

Use a separate custom pack or line when the structure represents an independent reusable part. Use an instance when it is an alternative version of one existing target.

Before opening Code Builder:

1. Switch through every variant and review the live preview.
2. Test condition values and confirm the expected lines and packs appear.
3. Resolve duplicate variant names, duplicate line names in the active variant, and duplicate field IDs reported by the issue list.
4. Check that every From Input default has a compatible defined input.
5. Confirm that output names, logic-flow titles, and error handlers form the contract you intend to implement.

The More actions menu can copy a test snapshot, import JSON text, import a JSON file, or download the visual configuration as JSON. Importing replaces the current draft configuration, while New Node asks for confirmation before clearing unsaved work. Use Publish for a new template or Update for an already-published template.

Continue to Code Builder to implement the visual contract. When the visual structure and code both pass review, follow Publish, Share, and Clone.