Custom Attributes

Custom attributes attach structured, per-run data to a Flow request. Use them for values that help you find and compare requests later, such as a customer tier, region, routing decision, experiment name, or review status.

Custom attributes have two parts:

1. The Flow's Custom Attributes Schema defines the available Trace Grid columns and their types.
2. A node sets the values for the current Flow request while the Flow runs.

The schema does not populate a value by itself. It tells BotDojo how to display and query values written by a run.

Custom attributes versus Flow Properties: Flow Properties configure reusable node settings, such as the model or index a Flow uses. Custom attributes record per-run facts so you can inspect, filter, and compare Flow requests.

Example: flag requests for review

This example adds three custom attributes:

Attribute	Type	Purpose
customer_tier	string	Segment requests by customer tier.
region	string	Find requests for a geographic region.
needs_review	boolean	Filter requests that require manual review.

The Flow receives customer_tier, region, and confidence. A Code node marks the request for review when confidence is below 0.75.

1. Define the schema

1. Open the Flow and select Flow Settings.
2. Select Advanced, then Custom Attributes.
3. Under Custom Attributes Schema, select Edit.
4. Add the fields in the table above, or turn on Show JSON Schema and enter the schema below.
5. Select Apply, then Update.

⤢Expand

Screenshot previewThe Edit JSON Schema dialog defining Customer Tier, Region, and Needs Review as top-level custom attributes.

×

{
  "schema": "https://botdojo.ai/schemas/text_input",
  "title": "Flow custom attributes",
  "type": "object",
  "properties": {
    "customer_tier": {
      "type": "string",
      "title": "Customer Tier"
    },
    "region": {
      "type": "string",
      "title": "Region"
    },
    "needs_review": {
      "type": "boolean",
      "title": "Needs Review"
    }
  },
  "required": []
}

Only top-level schema properties become individual Trace Grid columns. The property's title is used as the column label; when title is omitted, BotDojo uses the property name.

Choose types based on how you want to query the data:

• string values support text filters and sorting.
• number and integer values support numeric filters and sorting.
• boolean values support true/false filters and sorting.
• object and array values remain available as data, but their columns are not sortable or filterable.

2. Set the values during the run

Add a Code node on the execution path before the End node. Configure its input schema with customer_tier as a string, region as a string, and confidence as a number, then map the corresponding values into the node.

In the Code node's Runtime Options, turn on Allow Callbacks. This setting is required for the node to update the current Flow request.

Use context.setFlowRequestCustomAttributes(...) to set several values together:

async function execute(
  input: InputSchema,
  node: INode,
  context: IFlowContext,
): Promise<OutputSchema> {
  const needsReview = input.confidence < 0.75;

  await context.setFlowRequestCustomAttributes({
    customer_tier: input.customer_tier,
    region: input.region,
    needs_review: needsReview,
  });

  return {
    needs_review: needsReview,
  };
}

Define needs_review as a boolean in the Code node's output schema if another node also needs the result. Setting a custom attribute records the value on the Flow request; it does not automatically add that value to the Code node's output.

To set one field at a time, use the singular method:

await context.setFlowRequestCustomAttribute("needs_review", true);

Attribute keys cannot be empty or contain a period (.), and values must be JSON-serializable. Keep the keys and value types aligned with the schema so the Trace Grid can query them correctly.

3. Find the requests in Trace Grid

Run the Flow with a few different values, then open Trace.

1. Open the column selector.
2. Add Customer Tier, Region, and Needs Review to the grid.
3. Filter Needs Review to show requests where the value is true.
4. Add a region or customer-tier filter to narrow the results further.

Custom attribute columns are hidden until you add them to the grid. Their values remain attached to each Flow request and can be used to search and compare runs later.

When to use something else

• Use Flow Properties when a caller should configure how the Flow runs.
• Use Session State when data must persist across multiple requests in the same conversation or session.
• Return a value from the node when downstream nodes need it during the current run.

Next steps

• Learn how to define inputs, outputs, and runtime options in Code Nodes.
• Compare groups of requests with batch run comparisons.
• Use custom attributes alongside evaluations to filter the requests you want to review.